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Preface 


Manual Objectives 


This manual describes the DECnet/E services available to a FORTRAN pro- 
grammer, permitting him to code programs that exchange data with other 
programs running in a DECnet network. 


Intended Audience © 


This manual is written for the experienced programmer. While the reader is 
not expected to be knowledgeable of network programming, he is expected to 
be completely familiar with both the FORTRAN programming language and 
the general mechanisms for interfacing with the RSTS/E operating system. 
Either the FORTRAN-IV or the FORTRAN-IV-PLUS languages can be 
used. 


Prerequisite Reading 


The reader is expected to be completely familiar with the concepts and fea- 
tures of the FORTRAN programming language. Instructions on how to com- 
pile FORTRAN programs is given in the RT-11/RSTS/E F' ORTRAN IV 
User’s Guide. The RSTS/E Task Builder Manual describes TKB, the linker 
used for building RSTS/E tasks from compiled FORTRAN programs. 


The reader is also expected to be familiar with the concepts and features 
available for interfacing to the RSTS/E system monitor, as presented in the 
following manuals: 


RSTS/E System User’s Guide 
_ RSTS/E Programming Manual 


Related Documents 


To obtain a general understanding of the DECnet environment — internal 
and external — the reader is directed to the Introduction to DECnet. 


DECnet/E also provides utility programs that allow a terminal user to com- 
municate with another terminal user, to manipulate files across the network, 
and to copy the contents of one storage device to a device on another system. 
The information needed to run and use these utilities is given in the com- 
panion manual, DECnet/E Guide to User Utilities. 
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Two other companion manuals tell how to generate and start a DECnet/E 
system (the DECnet/E Network Installation Guide), control and manage a 
running DECnet/E system (the DECnet/E System Manager’s Guide), and 
give other information useful to a system manager. 


Three more DECnet/E manuals are available describing the DECnet/E mes- 
sage send/receive services for four other languages: 


DECnet/E Network Programming in MACRO-11 
DECnet/E Network Programming in BASIC-PLUS and BASIC-PLUS-2 
DECnet/E Network Programming in COBOL 


The more advanced network programmer may want to refer to the following 
two manuals for information concerning various network management func- 


tions: 


DIGIFAL Network Architecture, Network Services Fi unctional 
Specification 

DIGITAL Network Architecture, Network Management Functional 
Specification 


Structure of This Manual 


This manual is divided into three main parts. Part I, “Introduction,” presents 
a general discussion of the DECnet/E environment (Chapter 1). Part I, 
“Background Concepts for Network Programming,” presents a tutorial dis- 
cussion of the DECnet/E features available for sending and receiving mes- 
sages (Chapters 2 through 4). Part Ill, “Network Programming in FOR- 
TRAN,” describes the FORTRAN call formats used to access those features 
(Chapter 5). 


PART | 


INTRODUCTION 





Chapter 1 
introduction 


DECnet/E is a combination of hardware and software that extends the capa- 
bilities of a RSTS/E system running on a DIGITAL PDP-11 computer to 
allow a programmer to develop and execute programs that exchange data with 
remote programs running on another DECnet system in a network. 


NOTE 


Throughout this manual, the term remote program refers to 
any other program with which a program is communicating 
using the DECnet facilities. Such programs need not be located 
on another node in the network. It is possible to use DECnet/E 
to communicate with other programs at the local RSTS/E 
node. During development of network application programs, 
the whole system can be debugged locally and later distributed 
to remote nodes as required. 


This manual describes the features available to network programmers in the 
FORTRAN programming language on RSTS/E systems. 


1.1 Basic Terms and Concepts 


The term network is used here to refer to two or more computer systems 
connected such that they can exchange information. The computer systems, 
called nodes, are connected by communications paths called physical links. 
Physical links can be established through normal (switched) telephone cir- 
cuits, several varieties of leased (private) lines, coaxial cables, or even satellite 
transmission facilities provided by several carriers. 


In the network shown in Figure 1-1, a user at node BOSTON would refer to 
BOSTON as the local node and to nodes DENVER, DALLAS, LONDON, 
and LA as remote nodes. At node BOSTON, the nodes DENVER, DALLAS. 
and LONDON are physically adjacent nodes. That is, there is a direct phy- 
sical link to these nodes with no intervening nodes. To a user at node LA. 
DENVER is the only adjacent node. 


A path is the route over which data travels from its source to its destination 
within the network. Path length is the distance from the source node to the 
destination node, measured in hops. A hop is equal to a physical line between 
two adjacent nodes. In Figure 1-1, the path length between nodes DALLAS 
and BOSTON is one hop and between LA and LONDON is three hops. The 
network diameter is the maximum path length between any two nodes. The 
network shown in Figure 1-1 has a network diameter of three hops. 


Transmit Via Satellite 
(Physical Link) 





Figure 1-1: Computer Network Composed of Five Nodes 


1.2 DECnet Networks 
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DECnet as a whole refers to the hardware and software that allows different 
DIGITAL systems to be connected to form networks. DECnet has been de- 
signed to allow each system to function as a separate entity but still allow 
access to resources that are distributed throughout the various systems in the 
network. A DECnet/E system provides all the capabilities*of a normal 
RSTS/E system as well as the networking capabilities described in this 
manual and in the companion DECnet/E manuals listed in the Preface. 


All DECnet implementations are based on a design structure called the DIG- 
ITAL Network Architecture (DNA). This architecture allows network imple- 
mentations on the various DIGITAL systems to evolve (to provide more and 
more capability as time goes on) within a basic common structure. The struc- 
ture ensures that implementations providing fewer features will always work 
with implementations providing more. 


Perhaps a more immediate aspect of this process of evolution, however, is that 
at any given time capabilities can indeed differ from system to system. We do 
not attempt to describe here the DECnet implementations for all the different 
DIGITAL systems. Nevertheless, to use DECnet/E, you do need to give some 
thought to the other DIGITAL systems in your network. 
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If your network consists entirely of DECnet/E Version 2.0 nodes, this docu- 
ment provides all the information necessary for you to use DECnet/E to send 
and receive messages in FORTRAN programs. If your network contains other 
DECnet systems, however, you should check the DECnet documentation for 
those systems to be sure that the corresponding capabilities exist. For ex- 
ample, you can design network programs to be started automatically on 
RSTS/E systems. This feature is not available on all DECnet systems, how- 
ever, so your design should not necessarily assume this capability. 


A brief overview of the functional capabilities of the various DECnet imple- 
mentations can be found in Introduction to DECnet. 


1.3 The DIGITAL Network Architecture, (DNA) 


DECnet/E is implemented according to a set of rules, or protocols, governing 
the format, control, and sequencing of data exchange from the user program 
level down through the physical link level. These protocols are defined by the 
DIGITAL Network Architecture (DNA) — a logical structure that provides 
the model for all DECnet implementations. 


DNA consists of several layers, each defining a distinct set of network func- 
tions and a set of rules for implementing those functions. Each DECnet im- 
plementation consists of software modules that perform these DNA-defined 
functions according to DNA-defined protocols. The relevant protocols for net- 
work programming are called the Network Services Protocol (NSP). the 
Transport protocol, and the Digital Data Communications Message Protocol 
(DDCMP). 


The Network Services Protocol defines the rules for communication between 
programs in a network over paths called logical links. Logical links, described 
in detail in Chapter 2, allow many different data streams to be multiplexed 
onto the physical link for transmission and separated at the receiving node for 
delivery to the appropriate program. 


The Transport protocol defines the rules for determining the actual physical 
path, or route, along which data travels to its destination. 


Physical link control is achieved in DECnet by implementation of the Digital 
Data Communications Message Protocol (DDCMP). DDCMP ensures an 
error-free, sequential data path over a generally error-prone medium. This is 
accomplished with the Cyclic Redundancy Check (CRC) for error detection, 
retransmission for error corrections, and numbered data segments to ensure 
sequential transmission of data. 


1.4 Network Routing 


DECnet/E Version 2.0 is a Phase III DECnet product. (Refer to Introduction 
to DECnet for a discussion of the differences between Phase II and Phase III 
DECnet products.) As such, it supports the adaptive routing feature of Phase 
III, providing the user with the capability of communicating with other nodes 
in the network regardless of whether or not they are directly connected to the 
local node. 
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Networks can consist of the following three types of nodes: 


¢ Routing nodes — Phase III nodes connected to multiple communications 
lines, supporting route-through capabilities. 


e Nonrouting nodes (end nodes) — Phase III nodes connected to a single 
communications line. 


¢ Phase II nodes — nodes running a previous generation of the DECnet 
architecture. 


Phase III nodes can communicate with and are compatible with Phase II 
nodes. However, Phase II nodes do not acquire any new capabilities by being 
connected to Phase III nodes, and the restriction that Phase II nodes can only 
communicate with adjacent nodes continues to apply. Thus, a Phase II node 
can communicate with any other Phase III node, providing the path goes 
through Phase III nodes only. 


The adaptive routing feature is implemented through an algorithm that 
chooses the routing path with the lowest associated cost. Cost is computed as 
the sum of the costs of the lines over which the message is transmitted. The 
individual line cost parameters are assigned by the system manager and input 
into the system with the Network Control Program. (See the DECnet/E 
System Manager's Guide for a full discussion of line costs.) The algorithm 
automatically adjusts the routing when network topology or line cost changes 
occur. 


1.5 Overview of DECnet/E Structure 
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The DECnet/E features for network communication are implemented as part 
of the RSTS/E system monitor. The manner in which these features are 
accessed differs with the type of user. 


User programs interface with DECnet/E through NSP. Although it is not a 
separate entity or program, the term NSP is used throughout this manual to 
refer to the software that allows a user program to establish and exchange 
data over logical links. In other words, NSP is the implementation of the 
Network Services Protocol. The RSTS/E FORTRAN programmer accesses 
NSP services by coding calls to MACRO subroutines. NSP services can also 
be called from MACRO-11, BASIC-PLUS, BASIC-PLUS-2, or COBOL pro- 
grams, as described in associated DECnet/E Network Programming Manuals. 


Terminal users access certain network capabilities through various 
DECnet/E utility programs. The utilities TLK (Talk) and LSN (Listen) allow 
two terminal users to type messages to each other. The utilities NFT (Net- 
work File Transfer) and FAL (File Access Listener) work together to allow 
network file manipulation. They are implemented according to the Data Ac- 
cess Protocol (DAP) so that files can be exchanged with other DECnet sys- 
tems having the same capabilities: The NET utility allows the terminal user 
to log into and use a remote RSTS/E system as though the local terminal were 
directly connected to the remote system, and NETCPY copies entire devices 
between RSTS/E nodes. (See the DECnet/E Guide to User Utilities for details 
on these utility programs.) 
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The system manager uses the features provided by the Network Control 
Program (NCP) to monitor and control a node running in a network. (See the 
DECnet/E System Manager's Guide for details on running NCP.) 


Some elements of DECnet/E are not directly accessible to any user. These 
lower level elements of DECnet/E include the network Transport module 
(TRN) that implements the Transport protocol, several hardware devices (the 
DMC11, DMR11, DMV11, and DMP11), and their associated software device 
drivers. 


The device drivers are responsible for handling messages received from and 
sent over the physical communication lines. NSP gives a message to be 
transmitted to Transport, which selects an appropriate data path based on 
the destination of the message. Transport then passes the message to the 
proper device driver for actual transmission. The drivers manipulate the de- 
vice registers to cause message transmission to occur. 


To handle incoming messages, the drivers include buffer management func- 
tions that allow messages to be received from the physical links. When a 
message is received, it is passed to Transport, which checks the destination of 
the message. If the message is for the local node, Transport passes it to NSP 
for further processing. If the message is destined for another node in the 
network, Transport selects an outgoing data path and passes the message to 
one of the drivers for transmission. 


The hardware devices are intelligent communication controllers that connect 
the PDP-11 to physical communications lines. The DMC11 and the DMR11 
control lines that connect to only one other system in the network (point-to- 
point lines) ‘while the DMV11 and the DMP11 control lines that can connect 
to more than one other system (multipoint lines). The physical lines can 
include cables, modems and telephone circuits, or even satellite transmission 
facilities. Each controller contains a microprocessor, its own memory, and 
microcode that implements the DDCMP protocol. The implementation of 
DDCMP in firmware considerably reduces the software overhead for the 
DECnet/E system. 
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PART II 


- BACKGROUND CONCEPTS FOR NETWORK 
PROGRAMMING 
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Chapter 2 
Logical Links 


This chapter introduces the logical link — the basic element of DECnet task- 
to-task communication. A logical link is a software path for the exchange of 
data between two programs running in a network. 


Throughout the remainder of this chapter, and the two chapters that follow, 
various logical link parameters are discussed — object name and type code, 

Cc local and remote link address, flow control data request counts, and so on. 
These parameters can be observed on an operational node by issuing the NCP 
SHOW LINK command (for a single link) or the SHOW ACTIVE LINKS 
command (for all current links). This can be very helpful when debugging a 
network program. (See the DECnet/E System Manager's Guide for details on 
using the NCP commands.) 


In a network of DECnet nodes, many programs use the same physical path to 
exchange data. Data being sent from one program to another over a logical 
link is interspersed (multiplexed) with data sent over other logical links, 

Cc transmitted over the physical line, and separated (demultiplexed) at the re- 
ceiving end. The Network Services Protocol (NSP), implemented as a part of 
the DECnet software at each node, handles this multiplexing and demulti- 
plexing. It accepts outgoing data from local programs and formats it for trans- 
mission by the communications hardware. NSP also accepts incoming data 
from remote nodes and separates it into individual logical link streams that 
are then delivered to the appropriate local programs (see Figure 2-1). 


LOCAL NODE REMOTE NODE 


—ATA Fon 


all outgoing data 





Figure 2-1: NSP Handles Multiplexing and Demultiplexing of Data over 
Physical Lines 
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2.1 Creating a Logical Link 
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Creating a logical link is a cooperative venture. Two programs must agree to 
communicate before a logical link is established. The procedure is basically 
the same for all implementations of DECnet. The program that initiates the 
request for a logical link connection is called the source. The other program is 
called the target. This distinction is made only during the connection se- 
quence. 


NOTE 


Other network implementations make the’ source program the 
“link master.”” The source must poll the target for data and 
only the source can disconnect the link. DECnet does not make 
this distinction. Once the connection is established, the terms 
“source” and “target” have no significance and both the local 
and remote programs have equal access to the logical link. 


The request for a connection takes the form of a Connect Initiate Message 
that includes detailed information identifying the remote node and target 
program to which the connection is to be made. It also establishes an identi- 
fier for the link itself. In DECnet/E, the link identifier is called a user link 
address, or ULA. A ULA is a number from 1 to 255 that is used by the source 
program to refer to the link during subsequent send and receive operations. 


The NSP software at the source node does some initial checking of the request 
(to determine if it recognizes the remote node, for example). If all is well, the 
source NSP forwards the connect request to the NSP at the target node. The 
target NSP does its own checking to determine if the connection can be made. 
If the connection cannot be made, the target NSP rejects the connection. 
Otherwise, it delivers the connect request to the target program. The target 
program can then choose to accept or reject the logical link. 


If the target program accepts the link, it selects its own link identifier by 
which it will refer to the link. The two link identifiers are unrelated to one 
another. They can even take quite different forms if the programs are written 
in different languages or for different operating systems. If the remote node is 
a DECnet/E node, this identifier is again called a user link address and can 
range from 1 to 255. The number selected is completely independent of the 
selection made by the source program. The source and target NSPs relate the 
two identifiers to the same logical connection and keep the data exchanged 
over the link separate from data exchanged over other logical links. 


The target program’s confirmation or rejection of the link is passed back over 
the network to the source NSP, which passes this information on to the source 
program. This confirmation or rejection takes the form of a Connect Confirm 
or Connect Reject Message that is queued for the source to receive and pro- 
cess. 
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If the connection is confirmed after this mutual handshaking, the two pro- 
grams can then send and receive data over the link, each referring to the link 
by the identifier it assigned during the connection sequence. Both programs 
can send data simultaneously, since the DECnet software provides logical 
full-duplex transmission regardless of the characteristics of the intervening 
network. Either program can break the logical link connection when it is no 
longer needed. 


In Figure 2-2, A shows the procedure for establishing a logical link connection. 
The target NSP considers the link up (that is, it will allow the target program 
to send data) when the source NSP has acknowledged receipt of the Connect 
Confirm Message. The source NSP considers the link up when it receives the 
Connect Confirm Message. In Figures 2-2, B, C, and D illustrate the three 
ways in which a request for a link might be rejected. 


A Remote program confirms logical link connection 


LOCAL NODE REMOTE NODE 
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Node DENVER 






CONNECT INITIATE 


LOCAL NODE REMOTE NODE 
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8. Locat NSP returns an error on connect request 
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Figure 2-2: Logical Link Connections 


(continued on next page) 
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C. Remote NSP rejects logical link connection 


LOCAL NODE REMOTE NOOE 
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LOCAL NODE REMOTE NODE 


CONNECT REJECT 





0. Remote program rejects /ogical link connection 


LOCAL NODE REMOTE NOOE 


| want to tatk 
with PROGB at 
Node DENVER 





LOCAL NODE REMOTE NODE 






CONNECT REJECT 


Figure 2-2 (cont.): Logical Link Connections 


2.2 Advantages of Logical Links 
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In addition to making it possible to sort out the many physical streams of data 
that pass over a single physical line, the logical link structure maintained by 
NSP has several other advantages. 


e Reduction of addressing data required for message transmission, thereby 
providing efficient line usage 


¢ Separation of data into separate message streams 
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e Provision for high-priority Interrupt Messages 


e Ability to control the flow of data, thereby relieving possible network 
congestion 


2.2.1 Efficient Line Usage 


Once established, a logical link simplifies the addressing necessary for the 
exchange of data between two programs, both at the user’s level and in trans- 
mission of data across the network. As mentioned previously, a link identifier 
is assigned by each program to identify an established logical link. This iden- 
tifier is more convenient than the longer, detailed address used in identifying. 
the remote node and program in the original Connect Initiate Message. 


During a connection sequence, the source NSP and target NSP also establish 
a set of addresses that they use to identify the logical link. These addresses are 
called the local link address (LLA) and the remote link address (RLA), re- 
spectively. Each NSP refers to its own as the local link address and the other 
as the remote link address. 


While individual ULAs must be unique to the source program and to the 
target program, they are by no means required to be unique throughout the 
network, or even within the local node. Thus, the LLA and the RLA are 
required by NSP to separate the many distinct message streams that are 
multiplexed onto the communications lines. Since each NSP’s LLA is unique 
to its own node, these NSP addresses reduce the amount of control and identi- 
fying information that must accompany the user data transferred across the 


link (see Figure 2-3). 


Figure 2-4 illustrates how these addresses work, showing two DECnet/E nodes 
with two established logical links. Program A, for example, has established a 
logical link with Program D. Program A refers to the link with a user link 
address of 1. Program D refers to the link with a user link address of 23. Each 
NSP has established its own local link address. For Program A’s NSP, the 
LLA is 123456. For Program D’s NSP, the LLA is 024602. Each NSP keeps 
track of the other’s LLA as a remote link address. 


A. Message sent across the line for a connect request 


CONTROL AND ADDRESSING USER DATA 


B. Data message sent across the line over a logical link 


CONTROL AND ADDRESSING USER DATA 


Figure 2-3: Logical Links Provide Line Efficiency 
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Figure 2-4: User Link Addresses, Remote Link Addresses, and Local 
Link Addresses for Logical Links 


2.2.2 Separate Data by Intended Use 


Logical links provide a means by which incoming messages can be separated 
into different message streams. A program can establish different logical links 


- to communicate with different remote programs. Or it can establish several 


logical links with the same remote program to exchange data intended for 
different purposes. 


Before a program can use the message services, it must first register this 
intention with NSP. This involves declaring the name by which the program 
is to be known to other remote programs in the network (that is, its identity), 
as well as any limits or restrictions that will affect the way in which the 
program can use the message services. 


When a program declares its intent to use the network message services, NSP 
sets up a receive queue to hold pending messages. Thereafter, all messages 
received for the program are placed in the queue. Messages from different 
logical links are interspersed in the queue but the receiving program can 
retrieve either the first message in the queue or the first message from a 
particular logical link. 


The concept of separate message streams for separate logical links is illus- 
trated in Figure 2-5. 
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Figure 2-5: Data Is Queued for Logical Links in Separate Streams 


2.2.3 Interrupt Messages 


Special high-priority Interrupt Messages can be sent over logical links in all 
DECnet implementations. DECnet/E queues incoming Interrupt Messages at 
the head of the pending message queue, behind the first message in the queue 
(since the user program could be in the process of retrieving the first message) 
and behind any other pending Interrupt Messages queued for the program. 


In the DECnet/E implementation, these Interrupt Messages are not true in- 
terrupts in the sense of causing an immediate jump to an interrupt processing 
routine. (Some DECnet implementations do treat Interrupt Messages as true 
interrupts.) They are simply messages that can be identified as different from 
ordinary data messages and that are placed at the head of the pending mes- 
sage queue (see Figure 2-6). 


If a program is designed to send Interrupt Messages, the receiver at the other 
end of the link must be set up to process them. Interrupt Messages can 
contain a small amount of user data so that programs can be designed to 
recognize Interrupt Messages for different purposes. 


Interrupt Messages are discussed in more detail in Chapters 3 and 4. 
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Figure 2-6: Queuing of Interrupt Messages for Logical Links 


2.2.4 Flow Control 


NSP maintains each program’s queue of pending messages in system buffer 
space. A message is stored in the queue until it is received by the user pro- 
gram. Thus, pending messages tie up valuable system resources. Several flow 
control mechanisms are used in DECnet to protect systems from being flooded 
with messages. Some of these mechanisms are system-regulated while one 
mechanism is selected and controlled by the user program. 


Each receiver program.can select one of the following three types of program- 
regulated flow control: 


e Segment flow control 
¢ Message flow control 


e No active flow control 


A discussion of program-regulated flow control is given in Section 4.2.3. 


2.3 DECnet/E Logical Link Limitations 
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The implementation of DECnet for RSTS/E allows a maximum of 127 active 
logical links for the entire node at any one time. The system manager can 
reduce this maximum to some number between 1 and 127. There is no limit to 
the number of logical links per program other than the system maximum. 
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Chapter 3 
Overview of DECnet/E Message Services 


RSTS/E provides message services for communication between local pro- 
grams. The DECnet/E message services are implemented as an extension of 
these local services. In addition, DECnet/E offers new capabilities for local 
communication not found with the original RSTS/E message mechanism. The 
original local communication services are described in the RSTS/E Program- 
ming Manual. They are repeated in this document both for completeness and 
because they are the logical basis for the DECnet extensions. 


We emphasize here that it is the way in which the user interfaces with 
DECnet from RSTS/E that is implemented as an extension of local capabili- 
ties. An RSX-11 programmer might interface with DECnet somewhat differ- 
ently. The underlying architecture provides the consistency. The programmer 
at each system uses a familiar language.and form. DECnet handles both the 
transmission itself and the translation necessary at both nodes to convert the 
original call to a form that can be transmitted over the line and back to the 
format expected at the receiving node. 


Table 3-1 lists the calls used for interprogram communication by programs 
running under DECnet/E. The remaining sections of this chapter give a gen- 
eral description of each of the calls. Specific FORTRAN calls, with detailed 
formats, are given in Chapter 5. 


Table 3-1: Summary of Calls for Interprogram Communication 


Call Function 

Declare Receiver Registers the program with the operating system for 
message services. 

Remove Receiver Terminates message operations for the program. 

Get Local Node Parameters Obtains local node information. 

Log User Event Queues a user-generated event to the local event proc- 


essor for logging. 
Send Local Data Message Transmits user data to a local program. 


Send Connect Initiate Message Requests a logical link connection with another pro- 
gram. 


(continued on next page) 
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Table 3-1 (cont.): Summary of Calls for Interprogram Communication 


Call Function 

Send Connect Confirm Message Accepts a logical link connection requested by another 
program. 

Send Connect Reject Message Rejects a logical link connection requested by another 
program. 

Send Network Data Message Transmits user data to a network program over an es- 
tablished logical link. 

Send Interrupt Message Transmits interrupt data to a network program over an 
established logical link. 

Send Link Service Message Requests data over a flow controlled logical link. 

Send Disconnect Message Disconnects an established logical link, after all 


pending messages have been sent. 


Send Link Abort Message Disconnects an established logical link immediately, 
destroying any messages waiting to be sent. 


Receive Receives a message from the queue of pending mes- 
sages. (One of nine message types, corresponding to the 
nine Send calls listed above, could be received.) 


3.1 General Remarks 
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The Declare Receiver call informs the local RSTS/E monitor that the program 
issuing the call intends to communicate with other programs. This call identi- 
fies the program and defines which of the services will be required. The Re- 
move Receiver call is issued when message operations are complete for the 
program and releases system resources used for message services. The Get 
Local Node Parameters call returns information to the calling program con- 
cerning the local node. The Log User Event call permits a user-written pro- 
gram to queue ah event to the event processor for logging. 


Beyond these, the operations available fall into two categories: send and re- 
ceive. The entities sent and received are called messages. They consist of 
contro! information identifying the type of message, and in most cases, data of 
interest to the programs exchanging information. Nine message types are 
available for these operations. 


A separate call is used to send each of the message types. That is, there is a 
Send Connect Initiate Message call, a Send Local Data Message call, and so 
forth. When one of these calls is executed, NSP uses the parameters and user 
data included in the call to format the appropriate network message into 
system buffer space. Necessary header information is also included. This mes- 
sage is then queued to Transport for transmission across the network. The way 
in which a message is queued for transmission depends on the type of mes- 


sage. (A discussion of transmission queuing is given in Section 4.2.1.) 


The Receive call retrieves a message from the program’s queue of pending 
messages maintained by NSP in system buffer space. NSP queues incoming 
messages for the program as they come in across the network. Messages from 
local senders are also placed in the pending message queue. 
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NOTE 


Within the current context, local programs are programs run- 
ning at the local node that send messages using only the Send 
Local Data Message call. Network programs, on the other 
hand, are programs running either locally or remotely that use 
DECnet to establish and send data over logical links. 


The Receive call returns control information identifying the sender and the 
type of message (one of the nine listed previously in Table 3-1). User data 
accompanying the message is returned to a user buffer specified in the Receive 
call where it can then be examined and processed. 


A user program can issue general or selective Receive calls. On a general 
Receive, the first message in the queue is returned. A selective Receive can 
select the first message from any local sender, a particular local sender, any 
network sender, or a particular logical link. 


There can be times when no pending messages are in the queue when a 
Receive call is issued. One option available in the Receive call causes the 
program to ‘“‘sleep,” or suspend execution, until some action takes place — 
until a message is queued or a specified amount of time has passed, for 
example. The Receive call can also be issued to retrieve only part of a mes- 
sage. A program with limited buffer space can choose to retrieve only part of 
the user data with one Receive call. Subsequent Receive calls will retrieve the 
rest of the data, or the remaining data can be discarded. 


3.2 Registering with the Monitor: Declare Receiver Call 


A program declares its intent to use the message services by issuing a Declare 
Receiver call. This call must be executed before a program can send network 
messages or receive messages of any type. A program can, however, send local 
data messages without executing this call. 


The Declare Receiver call does more than just declare intent, however. It also 
defines the way in which other programs throughout the network are to ad- 
dress this program (the program’s identity) and the way in which the program 
can thereafter use the message services. 


The Declare Receiver call has some rather far-reaching effects. For this 
reason, the parameters specified with the call and how the system uses them 
are described here in detail. : 


3.2.1 Declaring Identity 


A Declare Receiver call identifies the calling program with an object type 
code, a name, or both. The manner in which a program declares its identity 
affects the way incoming link connections are handled. 


A name is an ASCII identifier that can be used by either local or network 
programs to refer to the declarer. No two programs at the local node can use 
the same name at the same time. If a name is given, it must be unique within 
the local node. 
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An object type code, on the other hand, is simply a number in the range of 1 to 
255. It can be used by other network programs to refer to the declarer. (Local 
programs cannot address a receiver by object code.) These codes simplify the 
identification of programs performing identical functions at different nodes of 
a network, without going through the cumbersome process of arriving at and 
enforcing standard naming conventions. 


An object code also need not be unique, and more than one receiver can 
declare identity with the same object code simultaneously. A program per- 
forming a general-purpose function of interest to the entire network can incur 
heavy use. By permitting more than one program to declare identity with the 
same object code at the same time, DECnet/E permits execution of multiple 
copies of a program to meet sporadic heavy usage. 


A range of object type codes (1 through 127) is reserved for DECnet use. The 
remainder (128 through 255) are available for user applications programs. 
Currently assigned object type codes for DECnet use are given in Appendix A. 


NOTE 


In the DECnet environment it is recommended that, whenever 
possible, programs declare their identity with and be addressed 
by nonzero object type codes. 


Network addressing is discussed in detail in Chapter 4. 


3.2.2 Declaring Intended Usage 


In addition to identifying the program, the Declare Receiver call defines how 
the program intends to use the message services. For example, a program can 
limit the incoming messages to those from local senders only. Or, it can limit 
incoming messages to those from network senders only. 


Other protective limits can be set in the Declare Receiver call. 


e The maximum amount of system buffer space to be used for the pending 
message queue. 


e The maximum number of messages that can be stored in the pending mes- 
sage queue. 


e The maximum number of active logical links that the program can have at 
any given time. 


These limits affect incoming messages and incoming requests for logical links. 
The Declare Receiver call does not limit the type or number of send calls a 
program can execute. 


3.2.3 DECnet/E Use of the Declare Receiver Call 


When a Declare Receiver call is issued, the system sets up a 32-byte Receiver 
ID Block (RIB) to associate the information with the RSTS/E job number. 
The Receiver ID Block actually applies to the job rather than the program 
that issues the Declare Receiver call. This distinction is rather fine for most 
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applications, but does make it possible, for example, to chain together a set of 
Cc programs using message services. The first program in the series would exe- 
cute a Declare Receiver call. Then other programs in the chain would also be 
valid receivers as long as they were always executed under the same job 


number. 


The Receiver ID Block holds the arguments passed with the Declare Receiver 
call, along with other system- and NSP-maintained information, such as the 
address pointers of the pending message queue and the address of the list of 
active logical links. 


3.3 Remove Receiver Call 


A Declare Receiver call remains in effect until a Remove Receiver call is 
issued. The Remove Receiver call releases the Receiver ID Block. All pending 
messages are discarded and all active logical links are destroyed. (NSP sends 
a Link Abort Message to the remote programs for any active logical links.) 


c Like the Declare Receiver call, the Remove Receiver call applies to the 
RSTS/E job. If a program does not issue a*Remove Receiver call before termi- 
nating execution, other programs executed later under this job number will be 
unable to issue a Declare Receiver call. (As far as the system is concerned, the 
old one is still in effect.) A Remove Receiver call should be issued as soon as 
message services are no longer needed. This practice prevents queuing of 
unwanted messages and releases the system buffer space used for the Receiver 
ID Block. 


Cc Also, any program that could be stopped by a terminal user’s CTRL/C should 
have provisions to issue a Remove Receiver call and terminate gracefully. If a 
job is killed, NSP automatically destroys any active logical links, discards 

messages, and releases any system resources used for message operations. 


NOTE 


It is generally good practice for a program to issue a Remove 

Receiver call immediately before issuing a Declare Receiver 

call. This prevents errors on the Declare Receiver call caused 

Cc by abnormal termination of a previous program running under 
the same job number. 


3.4 Get Local Node Parameters Call 


The Get Local Node Parameters call returns information to the calling pro- 
gram concerning the local node. This information consists of the node name, 
address, and alias (if any), and the node’s default project-programmer 
number (if any). (See the DECnet/E System Manager's Guide for a discussion 
of alias.) 


A general-purpose network program — one that runs on several different 
nodes rather than being specific to any one node — would use this call to 
obtain the node name, number, and alias for use in the connection sequence. 
The program uses this information to identify itself to the remote node and 
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program. A program that is started automatically as the result of an incoming 
connect request would use this call to obtain the default project-programmer 
number for use in validating the connection and logging into a user account. 
(See “Automatic Job Startup” in Chapter 4 for a discussion of the default 
account.) 


3.5 Log User Event Call 


The Log User Event system call permits a user-written program to queue an 
event to the system event processor for logging. Before an event is logged, it is 
time-stamped by the system in the standard Network Information and Con- 
trol Exchange (NICE) protocol. 


Optional parameter data can be passed to the event processor for processing 
and output. If it is included, this data must be in NICE protocol format. (See 
the DIGITAL Network Architecture, Network Management Functional Spec- 
ification, Version 3.0.0, for further information on event logging.) 


NOTE 


This system call performs a highly specialized function which 
requires a great deal of special knowledge of DECnet and the 
DIGITAL Network Architecture. It is provided as a conven- 
ience for the sophisticated network user and is not intended for 
normal network programs. 


3.6 Send/Receive Local Data Message 


The Send Local Data Message call transfers up to 532 bytes of user message 
data to a local program. The message is placed in the appropriate receive 
queue of the target program. The target program can be identified either by 
job number or by the name given in its Declare Receiver call. 


A Receive call that returns a Local Data Message returns control information 
identifying-it as a Local Data Message from a specific local sender, and up to 
532 bytes of user data. 


The Local Data Message is not used for DECnet communication but is in- 
cluded here for reference. A user program can carry on local conversations and 
maintain one or more DECnet logical links at the same time. 


3.7 Send/Receive Connect Initiate Message 
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The Send Connect Initiate Message call is used to request a logical link 
connection with a remote program. 


The target node and program are identified by a 120-byte Connect Data Block 
passed as part of the call. The following information is specified with the call: 


The user link address (ULA) that the source program will use to refer to 
this link. 
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The type of receiver flow control desired by this program — that is, the 
type of flow control to be imposed on incoming data messages. (A full 
discussion of flow control is deferred to Chapter 4.) 


A receive maximum. The maximum amount of data to be received by the 
program over this link in one Network Data Message. The size of the 
receive buffers allocated by NSP will also limit the amount of data that 
can be passed in a single Network Data Message. If the maximum buffer 
size set by Network Management for NSP is not large enough to handle 
the receive maximum as specified by the user program, NSP will alter the 
receive maximum to the smaller limit before forwarding the Connect Ini- 
tiate Message. The local program is informed of this change (if any is 
made) by a field in the Connect Confirm Message from the remote pro- 
gram when it accepts the link. 


A Connect Data Block identifying the target node and program to which 
the connection is requested. The target program can be identified by name 
or object type code. NSP inserts the local program identification, as speci- 
fied in the source program’s Declare Receiver call, into the Connect Data 
Block. This allows the remote program to determine who sent the connect 
request and decide whether to accept or reject the connection. The Con- 
nect Data Block can also contain data required by the remote program or 
system for access control. Such data might consist of a project-pro- 
grammer number, password, and account number — or whatever is re- 
quired by the remote program or system. 


Up to 16 bytes of user data. 


A Receive call that returns a Connect Initiate Message from the queue of 
pending messages returns control information identifying it as a Connect 
Initiate Message from a specific network program, and requirements imposed 
by the remote program. The information includes the following: 


The local link address (LLA) assigned by the local NSP to refer to this 
logical link. The program will use the LLA to refer to the link in its 
responding Connect Confirm or Connect Reject Message. (Note that the 
LLA is only used to refer to a link while no user link address (ULA) is in 
effect. The ULA is established by the receiving program in its Connect 
Confirm Message that accepts the connect request and is used thereafter 
by the program to refer to the link.) 


The type of receive flow control desired by the remote program — that is, 
the type of flow control that will be imposed on outgoing data messages 
over this link. 


A receive maximum. The maximum amount of user data that can be 
received by the local program over the link. This maximum is calculated 
by the local NSP, based on the size of receive buffers it allocates. The 
program can reduce this maximum further in its responding Connect Con- 
firm Message. 


A transmit maximum. The maximum amount of user data that can be 
transmitted by the program over this logical link in one Network Data 
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Message. This maximum is imposed by either the remote NSP or the 
remote program and corresponds to the remote program's receive max- 
imum. 


A 120-byte Connect Data Block, identifying the remote node and program 
requesting the link. The Connect Data Block also indicates how the re- 
mote program addressed this one (by name or object type code). If the 
program requires access control information from the remote program, 
such information would also be included as part of the Connect Data 
Block. The Connect Data Block and up to 16 bytes of user data are deliv- 
ered to the user buffer specified in the Receive call. 


3.8 Send/Receive Connect Confirm Message 
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The Send Connect Confirm Message call is used to accept a logical link 
requested by a remote program. That is, it is a positive response to a received 
Connect Initiate Message. The following information is specified with the call: 


The user link address (ULA) by which the program will hereafter refer to 
this link. 


The local link address (LLA) that identifies the link being accepted. (The 
LLA is taken from the Connect Initiate Message received for this partic- 
ular link.) 


The type of receive flow control desired by the calling program for in- 
coming data messages over this link. (Flow control options are discussed 
in detail in Chapter 4.) 


A receive maximum. The maximum amount of user data that the program 
wishes to receive as a unit (that is, as one Network Data Message). 


Up to 16 bytes of user data. 


A Receive call that returns a Connect Confirm Message from the pending 
message queue returns control information identifying it as such, along with 
requirements for messages to be transmitted over the link. The information 
includes the following: 


The user link address (ULA) established by the receiving program in the 
Connect Initiate Message that requested the link. This identifies the par- 
ticular link being confirmed. 


The type of receive flow control requested by the remote program — that 
is, the type of flow control imposed on outgoing data messages. (Flow 
control options are discussed in detail in Chapter 4.) 


A receive maximum. The maximum amount of user data that the local 
program will receive on this link in one Network Data Message. This will 
be the same or less than the size requested in the program's Connect 
Initiate Message. A smaller size is indicated by the local NSP if it cannot 
handle the size requested in the Connect Initiate Message. 
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A transmit maximum. The maximum amount of data the local program 
can send to the remote program as a unit (with one Network Data Mes- 
Cc sage) over this link. 


Up to 16 bytes of user data, delivered to the user buffer specified in the 
Receive call. 


3.9 Send/Receive Connect Reject Message 


A Send Connect Reject Message call is used to reject a logical link requested 
by a remote program. That is, it is a negative response to a received Connect 
Initiate Message. The following information is specified with the call: 


The local link address (LLA) assigned by the local NSP to identify the 
link being rejected. (The local link address is taken from the received 
Connect Initiate Message.) 


A code identifying the reason for the rejection. Ordinarily, this code is zero 
¢ unless the program is rejecting the connection due to some standard 
reason, such as “invalid accounting data.” 


Up to 16 bytes of user data. 


A Receive call that returns a Connect Reject Message from the queue returns 
control information identifying it as such and the following information: 


A user link address identifying the link being rejected. This user link 

. address will be the same as that established by the local program in the 

Cc Connect Initiate Message that requested the link. The link could have 
been rejected by either the remote NSP or the remote program. 


A code identifying the reason for the rejection if the link was rejected by 
the remote NSP or by the remote program for some standard reason, such 
as “invalid accounting data.” (A list of NSP rejection codes is found in 
Appendix B.) 


Up to 16 bytes of user data, if the link was rejected by the remote program 
for some nonstandard reason. This data will be delivered to the user buffer 
é specified in the Receive call. 


3.10 Send/Receive Network Data Message 


The Send Network Data Message call transmits user information to a remote 
program over an established logical link. The logical link is identified by the 
user link address (ULA) established by the calling program in its Connect 
Initiate or Connect Confirm Message. The amount of user data that can be 
sent is limited to the transmit maximum established by the remote program 
(see the previous discussion of a received Connect Initiate or Connect Confirm 
Message). Sending a Network Data Message is subject to flow control im- 
posed by the system and by the remote program, as indicated by the flow 
control option selected by the remote program. A program can request that 
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link status information be returned by a Send Network Data call and use the 
information returned to schedule subsequent send and receive requests. A full 
discussion of flow control is deferred to Chapter 4. 


A Receive call that returns a Network Data Message returns identifying con- 
trol information and delivers the user data to a buffer specified in the call. 
The-amount of user data received in one Network Data Message will not 
exceed the receive maximum established by this program for the logical link 
(see the previous discussion of a sent Connect Initiate or Connect Confirm 
Message). Incoming Network Data Messages are subject to system flow con- 
trol and to the flow control option, if any, requested by the local program in its 
Connect Initiate or Connect Confirm Message. If the program requests flow 
control, it must send Link Service Messages to request data from the remote 
program (see Chapter 4). 


3.11 Send/Receive Interrupt Message 


The Send Interrupt Message call is used to transmit high-priority data toa 
remote program over an established logical link. All DECnet systems main- 
tain separate data streams for Interrupt and Data Messages. The Interrupt 
Message will be delivered to the remote program ahead of all Data Messages 
waiting to be processed at the remote end. Up to 16 bytes of user data can be 
sent in an Interrupt Message. Sending an Interrupt Message is subject. to flow 
control imposed by the remote system or program. The local program can 
request that link status information be returned following a Send Interrupt 
Message call and use the information returned to schedule subsequent send 
and receive requests. A full discussion of flow control is given in Chapter 4. 


A Receive call that returns an Interrupt Message returns identifying control 
information and delivers up to 16 bytes of user data to a buffer specified in the 
call. The Interrupt Message will have been queued at the head of the pending 
message queue, behind the first Data Message and behind any other pending 
Interrupt Messages queued for the program. Incoming Interrupt Messages are 
subject to flow control imposed by the local NSP. After receiving each Inter- 
rupt Message, the local program must send a Link Service Message to reen- 
able incoming Interrupt Messages from the remote program over a logical link 
(see Chapter 4). 


3.12 Send/Receive Link Service Message 
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The Send Link Service Message call is used to request data over a logical link 
— either to request data from a remote program over a flow controlled link, or 
to reenable incoming Interrupt Messages from the remote program. In these 
two cases, detailed link status information can be returned or the call can be 
issued solely to obtain this information. . 


A Link Service Message is returned on a Receive call when a link becomes 
unblocked. If a local program has tried to send a Network Data or Interrupt 
Message and failed because the remote system or program has inhibited flow, 
the local NSP informs the local program when the condition clears. To en- 
courage efficient processing of pending messages, NSP returns a Link Service 
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Message on a Receive call only when the pending message queue is empty. 
Detailed link status information is returned that the local program can use in 
regulating its send and receive requests. (The format of the status information 
for a received Link Service Message is the same as that returned, upon re- 
quest, for a Send Network Data, Interrupt, or Link Service call.) 


For a more complete understanding of the uses of Link Service Messages, see 
the discussion of flow control in Chapter 4. 


3.13 Send/Receive Disconnect Message 


The Send Disconnect Message call is used to break an established logical link 
provided that all Network Data, Interrupt, and Link Service Messages previ- 
ously sent over the link have been acknowledged by the remote NSP. If they 
have not been acknowledged, the call will terminate with an error and the link 
will not be broken. Successful completion of the call means that no more 
messages can be sent over the link. The user link address is freed and can be 
used to establish another logical link. However, messages already in the 
pending message queue will remain. They can (and should) be cleared from 
the queue by doing selective Receive calls using the user link address of the 
disconnected link. Once the link has been disconnected, new messages 
received for the link will be discarded by NSP. The Disconnect Message is 
sent to the remote system. When it is received by the remote NSP, the link is 
broken at that end. Up to 16 bytes of user data can be sent with a Disconnect 
Message. 


A Receive call that returns a Disconnect Message from the pending message 
queue returns control information identifying it as such, as well as a user link 
‘address and up to 16 bytes of user data. Receipt of a Disconnect Message 
indicates that the remote program has terminated the logical link. Further- 
more, it indicates that all previous Network Data Messages, Interrupt Mes- 
sages, and Link Service Messages sent by the remote program were placed in 
the pending message queue by the local NSP before the Disconnect Message 
was received. Once the Disconnect Message is received by the local NSP, the 
local program cannot send any more messages over the link. 


The Disconnect Message is useful in “master-slave” communication when the 
master program only transmits data and the slave program only receives data. 
Since there is no two-way communication, the master program can issue a 
Disconnect Message to break the link with the assurance that the remote 
system has received all the data sent and queued it for the slave program. 
Successfully completing the disconnect does not guarantee that the slave has 
processed the data, however. Where such guarantees are desirable, or where 
two-way communication is desired, programs should agree to terminate the 
logical link by exchanging Network Data Messages, Interrupt Messages, or 
whatever. 


3.14 Send/Receive Link Abort Message 


A Send Link Abort Message is used to break a logical link immediately. 
Unlike a disconnect, no attempt is made to ensure that messages previously 
sent over the link have been acknowledged by the remote system. In fact, NSP 
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discards any messages it has queued for transmission for the link. (Section 
4.2.1 describes NSP transmit queuing.) No further data can be sent over this 
logical link. Received messages already in the pending message queue will 
remain but new messages received after the Link Abort Message is issued will 
not be queued for the link. Messages already in the queue can (and should) be 
cleared by doing selective Receive calls using the user link address of the 
aborted link. 


If the link is established, the Link Abort Message is sent to the remote system 
as notification that the link is broken and up to 16 bytes of user data can 
accompany the Link Abort Message. A Link Abort Message can also be sent 
for a logical link that has not yet been confirmed by the remote program. In 
this case, NSP breaks the link at the local node, but it does not notify the 
remote system. (Hence, the user data does not reach the remote program.) 
Should the remote program confirm the link, the local NSP no longer knows 
the link and it so informs the remote NSP, which notifies the remote program. 
Should the remote program reject the link, the local NSP informs the remote 
NSP that it has no such link but since the remote program rejected the link 
anyway, no notification is given to the remote program. 


A Receive call that returns a Link Abort Message from the pending message 
queue returns control information identifying it as such, as well as a user link 
address and a local link address to identify the link aborted. The local link 
address identifies a link aborted during the initial connection sequence. For 
example, if the local NSP received a Connect Initiate Message, but the local 
program has not yet responded with a Connect Confirm or Connect Reject 
Message, a Link Abort Message is queued with the same local link address as 
was specified in the received Connect Initiate Message. The link could have 
been aborted by the remote NSP or the remote program. If the link was 
aborted by the remote NSP, the message will contain a reason code identi- 
fying the reason for the rejection. If the link was aborted by the remote 
program, up to 16 bytes of user data can also be delivered with the Link Abort 
Message. Once the local NSP receives the Link Abort Message, the local 
program cannot send any more messages over the link. 
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Chapter 4 
Network Addressing and Flow Control 


With the background given in Chapters 2 and 3, we can now discuss two areas 
of interprogram communication in a DECnet network: network addressing 
and flow control. Network addressing concerns the methods whereby a pro- 
gram declares its identity for the purpose of receiving network messages. Flow 
control involves the various techniques used by DECnet to ensure an orderly 
transfer of message and control data between nodes in a network. 


4.1 Network Addressing 


When a program declares its intent to use the network message services, it is 
influenced by the following DECnet/E features: 


¢ The options available in the Declare Receiver call 


e The way in which DECnet/E NSP handles incoming requests for logical link 
connections 


e The multiple copy execution feature, by which more than one copy of a 
network program can be executed in the RSTS/E timesharing environment 


¢ The automatic job startup feature, by which DECnet/E allows programs to 
be defined by the system manager for automatic startup on receiving a 
request for a logical link connection 


4.1.1 Declaring Network Names and Object Type Codes 


Every DECnet/E program that wishes to receive messages from local senders 
or establish logical links for data exchange with other network programs must 
declare its identity in a Declare Receiver call. The program can declare its 
identity with a nonzero object type and with a null name — abbreviated to 
DR(n,null) in this chapter — with a zero object type and a nonnull name — 
DR(0,name) — or with a nonzero object type code and a nonnull name -- 
DR(n,name). Remember from the discussion in Chapter 3 that nonzero object 
type codes should be used consistently throughout the network. 
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Declaring identity by object type code alone — DR(n,null) — permits mul- 
tiple copies of a program to be executed without the necessity of generating a 
unique identity for each copy. DECnet/E allows more than one program to 
run and declare identity with the same object type code. Thus, several copies 
of a program can be executed simultaneously in response to incoming connect 
requests. 


On the other hand, declaring identity by name alone — DR(0,name) — re- 
quires uniqueness in the sense that no other program at the local node can 
declare identity with the same name at the same time. If a program declares 
its identity with the same name each time it runs, multiple copies cannot 
execute simultaneously. 


It is possible, however, to combine the features of uniqueness and of multiple 
copy execution. By appending the RSTS/E job number to a common root, a 
program can create a unique, nonnull name — for example, FAL21, FAL05. 
(The RSTS/E job number is not directly accessible to a FORTRAN program 
but can be determined by executing a MACRO-11 subroutine that uses the 
UU.SYS directive, described in the RSTS/E System Directives Manual.) The 
program can then declare its identity with both the name created and a 
nonzero object type code. This permits multiple copies of the program to be 
run as a result of incoming connect requests but permits each copy to create 
its own unique identity. 


4.1.2 Handling of incoming Connect Requests 


When a Connect Initiate Message is received at the local node, NSP searches 
its list of Receiver ID Blocks for the proper receiver. (All other incoming 
messages reference an established logical link and will be queued to the cor- 
rect program without searching the list of Receiver ID Blocks.) The method of 
addressing specified in the Connect Initiate Message determines how NSP 
processes the request. 


Incoming requests for logical link connections can be addressed to either an 
object type code alone — CI(n,null) — or to a name alone — Cl(0,name). 
DECnet/E does not allow incoming connect requests to be addressed using 
both object type code and name. It will reject such requests, sending back a 
Connect Reject Message with a reason code indicating that the requested 
program cannot be found. 


Incoming Connect Request Addressed to Object Type Code — Cl(n,null) 


If the incoming Connect Initiate Message is addressed to an object type code 
— Cl(n,null) — NSP checks its Receiver ID Blocks to see if one or more 
programs are running that have declared identity with this object type code. 
The Declare Receiver call could have specified either DR(n,null) or 


- DR(n,name). 
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If one or more such receivers are found that have not reached their declared 
logical link maximum or message maximum, NSP queues the connect request 
for the first such receiver in its list (ordered by job number). 


NOTE 


Remember from Chapter 3 that a program sets its own limits 
on the number of logical links allowed and the size of the 
pending message queue in the Declare Receiver call. 


If there is no such receiver or if there are one or more such receivers but all 
have reached their declared logical link maximum or message maximum, 
NSP attempts to start another copy of the program. This process is described 
fully in Section 4.1.4 and also in the DECnet/E System Manager's Guide. 
Briefly, NSP checks to see if the program identified in the Connect Initiate 
Message has been defined by the system manager for automatic startup. If so, 
NSP creates a job and starts the program. The program must then issue a 
Declare Receiver call with the appropriate object type code. This creates a 
Receiver ID Block and a pending message queue to which the waiting Connect 
Initiate Message can then be transferred. If the program does not issue a 
Declare Receiver call within two minutes, NSP rejects the link by returning a 
Connect Reject Message to the remote program.» 


Incoming Connect Request Addressed to Name — Ci(0,name) 


When the incoming Connect Initiate Message is addressed to a name — 
Cl(0,name) — NSP checks its list of Receiver ID Blocks to see if a program is 
running that declared its identity with this name. The Declare Receiver call 
could have specified either DR(0,name) or DR(n,name). 


If such a receiver program is running, and it has not yet reached its declared 
logical link maximum or message maximum, the Connect Initiate Message is 
placed in the receiver’s queue of pending messages. 


If no such program is running, NSP will attempt to start the program. If it is 
successful in doing so, the program started must declare its identity with the 
appropriate name. Again, if the program fails to issue a Declare Receiver call 
within two minutes, NSP rejects the connection. 


If such a program is running, but it has reached its declared logical link 
maximum or message maximum, NSP rejects the connection, returning a 
Connect Reject Message with an appropriate reason code explaining the rejec- 
tion. Automatic startup is not attempted in this case, because a program is 
already running with the name to which the Connect Initiate Message. was 
addressed. A second copy with the same name cannot be generated since 
receiver names must be unique. 
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4.1.3 Multiple Copies 


In a DECnet/E system, multiple copies of a program can be started by a local 
terminal user, through the RSTS/E BATCH processor, or through the auto- 
matic job startup feature. The manner in which copies of a program can be 
started has some bearing on the way in which a Declare Receiver call should 
be issued. 


Multiple Copies Initiated by Terminal Users 


A program run from a local terminal with the purpose of communicating with 
a remote program will normally send at least the initial Connect Initiate 
Message requesting a logical link. (It is unlikely that remote users would wish 
to have the success of incoming link connections rely upon someone starting 
the program manually.) 


In this case, the program can declare its identity with DR(n,null), or with 
DR(n.name) or DR(0,name) as long as the program generates a unique name 
with each copy, as described in Section 4.1.1. The choice depends on whether 
or not the program receives any connect requests, and if so, if it is necessary 
for the remote program to connect with a specific copy. 


Suppose, for example, that the local program issues the initial Connect Ini- 
tiate Message for establishing the first logical link. Suppose further that it is 
then necessary for the remote program to establish a second logical link with 
the same copy that sent the Connect Initiate Message for the first link. The 
local program can declare its identity with either the form DR(0,name) or 
DR(n,name). The unique copy name is passed to the remote program in the 
Connect Data Block in the Connect Initiate Message. The remote program 
can then address its connect request in the form CI(0,name) to ensure that the 
request is delivered to the same copy that issued the first Connect Initiate 
Message. 


Multiple Copies Executed under BATCH 


Multiple copies of a program can also be executed through use of the RSTS/E 
BATCH processor (see the RSTS/E System User's Guide). Again, such pro- 
grams will normally be responsible for initiating at least the first logical link 
connection. The techniques described previously for multiple copies started 
by terminal users would also apply here. 


Multiple Copies Initiated through Automatic Startup 


Multiple copies of a program can also be initiated for programs that the 
system manager has designated for automatic job startup. Such copies result 
from incoming connection requests addressed CI(n,null). (See Section 4.1.4 
for full-details.) The local program can declare its identity with DR(n.null), or 
with DR(n,name) as long as the name is unique for each copy. 
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4.1.4 Automatic Job Startup 


Using the Network Control Program (NCP), the system manager can install 
user programs for automatic startup. Such programs reside as files on disk in 
the normal fashion and can be started by NSP to fulfill incoming requests for 
logical link connections (see Section 4.1.2). This installation method is de- 
scribed fully in the DECnet/E System Manager's Guide. Briefly, a DEFINE 
OBJECT or SET OBJECT command in NCP relates the file name to, again, 
an object type code, a name, or both. These commands also allow two param- 
eters to be associated with a program. The second parameter is made avail- 
able to the program when it is started automatically. (The first parameter is 
used as a starting line number for BASIC-PLUS or BASIC-PLUS-2 pro- 
grams. It is ignored for FORTRAN programs.) 


NSP maintains a:list of these definitions in its parameter file. The definitions 
are ordered by object type code, and thus, there can be only one program 
defined for automatic startup for each object type code. In particular, there 
can be only one program defined for automatic startup with an object type 
code of zero — (0,name). 


When a program must be started automatically, NSP checks the object type 
code or name given in the incoming connect request against its list of defined 
programs. If a match is found, NSP executes a monitor request to run the 
program as a detached job under RSTS/E. 


Once started, the program must declare its identity with the object type code 
or name that was specified in the Connect Initiate Message that caused the 
program to be started. If it does not, the connect request will never be deliv- 
ered to the proper pending message queue. 


NSP passes this information to the started program in core common. Any 
optional parameter established by the DEFINE OBJECT or SET OBJECT 
command is also passed in the string. A FORTRAN program cannot access 
core common directly, but a MACRO subroutine can be used to retrieve the 
data. (See the RSTS/E System Directives Manual.) The format of the core 
common string is as follows: 


Byte(s) Contents 

CORCMN-+0 Length of data in core common 

+1 Object type code (0-255) 

+2-7 Name (ASCII) 

+8-9 Second DEFINE parameter (-32768 through 32767) 
+10 Reserved 


The mnemonic CORCMN is assigned by the file COMMON.MAC to octal — 
location 460 (see the RSTS/E System Directives Manual). 


If the object type code in byte 1 of core common is nonzero, the program must 
declare its identity with that object type code. It can also use a nonnull 
unique name, if desired. If the object type code is zero, the program must 
declare its identity with the name given in bytes 2-7 of core common. It can 
also declare its identity with a nonzero object type, if desired. 
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When the Declare Receiver call is issued, NSP transfers the waiting connect 
request to the program’s queue of pending messages as a Connect Initiate 
Message. NSP waits two minutes from the time it starts the program for the 
connect request to be transferred. 


If the connect request is not transferred to a queue within this time period. 
NSP fejects the connection, sending a Connect Reject Message to the remote 
program. Since the remote program could also abort the link within this 
period, the first action of an automatically started program (after issuing the 
Declare Receiver call) should be to issue a Receive call to check for pending 
messages. If there are none, the program should issue a Remove Receiver call, 
and terminate execution with the Kill Job system call. (This call is not di- 
rectly accessible to a FORTRAN program but can be executed through a 
MACRO subroutine using the UU.CHU system call. See the RSTS/E System 
Directives Manual). Once the connect request has been received, the program 
should respond to the request immediately. While the local NSP’s timer is 
stopped when the message is transferred to the receiver's pending message 
queue. the remote node could be executing a timeout on the Connect Initiate 
Message. 


A program that has been started in response to an incoming Connect Initiate 
Message runs as a privileged RSTS/E user, and it is the responsibility of that 
program to protect the rest of the system from unauthorized outside access. 
Thus, after receiving the Connect Initiate Message, the program should check 
the accounting information passed in the Connect Data Block to determine 
the user account (and, therefore, the privilege level) in which it should run. If 
no such information is specified in the Connect Data Block, the program 
should issue a Get Local Node Parameters call to obtain the local node's 
default project-programmer number, if any. If a default account has been 
specified, the program should then look up the password for that account 
using the Read Accounting Data system call and log into the default account. 
(These system functions are not directly accessible to a FORTRAN program 
but can be executed through MACRO subroutines using the UU.RAD and 
UU.LIN system calls. See the RSTS/E System Directives Manual). If the 
local node has no default account, the connect request should be rejected. 
(Programs that always log into a predetermined account need not go through 
this procedure.) 


4.1.5 Examples of Network Addressing 


This section presents three examples of network addressing using the features 
just discussed. 


. The first example (Figure 4-1) shows the network addressing used by two 


DECnet/E utility routines — the Network File Transfer utility (NFT) and the 
File Access Listener (FAL). NFT is run by local users to connect with a 
remote FAL to access files at remote nodes. FAL is run at the local node as a 
result of incoming connect requests from a remote NFT. Both programs are 
designed to execute multiple copies as demand requires. 
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Since NFT is started only by local terminal users and never by remote re- 
quest, an object type code is not necessary. NFT is loaded from the system 
disk and declares its identity with an object type code of zero and a unique 
name each time it is run. NFT issues the Connect Initiate Message to estab- 
lish a logical link for thé transfer of data to or from remote nodes as specified 
by the user. 


Copies of FAL are started by incoming Connect Initiate Messages addressed 
to object type code 17. FAL declares its identity with object type code 17 and 
a unique name. It also declares that the maximum number of logical links 
allowed is one so each incoming connect request starts a new Copy. 


LOCAL NODE 













CONNECT INITIATE 


REMOTE 
NODE 
CONNECT INITIATE 







CONNECT INITIATE 


REMOTE 
NODE 








CONNECT INITIATE 


Figure 4-1: Network Addressing Used by NFT and FAL 


The second example (Figure 4-2) shows NETCPY, a device copying program 
that can be started either by local terminal users or by incoming connect 
requests. The program copies an entire device between nodes. Multiple copies 
are executed according to demand. Here, the Declare Receiver call is different 
depending on how the program is started. NETCPY is a BASIC-PLUS pro- 
gram and takes advantage of the starting line number feature. Using the 
Network Command Program (NCP), the system manager issues a command 
to SET or DEFINE NETCPY.BAC as object 20, with a starting line number 
of 29000. If NETCPY is started by a Connect Initiate Message from a remote 
program addressed to object type code 20, the program declares its identity 
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with object type code 20, a unique name, and a link maximum of one. If it is 
started by a local terminal user, it declares its identity with an object type 
code of 0, a unique name, and a link maximum of zero. Declaring a zero link 
maximum ensures that a program started by a local user will never have a 
Connect Initiate Message queued from a remote program. 


NETCPY.BAC 
1§ 20 STARTING 
LINE 29000 
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™e ~ 
Me, She 
~~ 


0 (CODE FOR START 
BY LOCAL USER) 


MAIN BODY 
OF CODE 











29000 (CODE FOR 
REMOTE START) 





Figure 4-2: Network Addressing Example — Different Declare Receiver 
for Local and Remote Start 


The third example (Figure 4-3) shows a program that can be run either by a 
local terminal user or as a result of an incoming connect request. The local 
terminal user is presented with a data display. Parameters are selected by the 
user and passed to a remote program monitoring a data gathering device. At 
the end of the-day, the remote program passes the data back to the local 
program for analysis and to the local terminal user, who repeats the process. 


Since only one copy of the program is ever needed at any given time, it 
declares its identity with a zero object type code and the name STAT. It is 
stored as file RSTAT.SAV on disk, where it can be run by the local user. 
Using NCP, the system manager has issued a command to SET or DEFINE 
RSTAT.SAV as STAT. 
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Figure 4-3: Network Addressing Example — Declaring identity by 
Name Alone 


4.2 Flow Control 


DECnet flow control protects user programs as well as entire systems from 
being flooded with more messages than can be processed at any given time. 


A DECnet/E sender is subject to flow control regulations imposed by the local 
NSP, the remote NSP, and the remote program (if the remote program re- 
quested flow control when the link was established). As a receiver, a 
DECnet/E program can select from three flow control options for a logical link 
to regulate the amount of data sent to it by the remote program. 


As a sender and/or receiver, a program must deal with the following four 
aspects of DECnet/E operation: . 


e Transmit queue management, imposed by the local (sending) NSP, en- 
sures that a local program does not use too much system buffer space for 
transmission. 
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¢ Backpressure flow control, imposed by the remote NSP, is used as a 
safeguard against excessive incoming data messages. 


Data Message flow control, imposed by receiving user programs, enables a 
program to control the flow of data to it. Both programs using a logical link 
can‘(independently) choose to receive network messages only when they 
specifically request data from the other program; or each can choose no flow 
control, placing no restrictions on the amount of data that they will receive. 


Interrupt Message flow control, imposed by either the remote NSP or the 
remote program (depending on the DECnet implementation), protects 
against Interrupt Message congestion. A DECnet/E program can receive 
only one unsolicited Interrupt Message over a link. After that, the program 
must request an Interrupt Message before the remote program can send one. 


4.2.1 Transmit Queue Management 


Once a logical link is established, DECnet/E maintains two transmit queues 
for the link: a transmit queue for Network Data Messages and a transmit 
queue for Interrupt and Link Service Messages. Both queues hold messages 
waiting for acknowledgment from the remote NSP. 


For example, when a DECnet/E program sends a Network Data Message to a 
remote program over a logical link, the message is queued to the Transport 
software for transmission and is also placed in the data transmit queue. The 
Network Data Message is held there until the local NSP receives an acknowl- 
edgment from the remote NSP indicating that it has received the message. 


If NSP does not receive an acknowledgment within a reasonable period of 
time, it assumes that the message has been lost and requeues it to Transport 
for retransmission. If the message has not been successfully transmitted after 
a specific number of retries, NSP aborts the link with a reason code indicating 
that the remote system is not responding. 


The timeout period used depends on the message type. For outgoing Connect 
Initiate Messages, a predetermined value is used. Once a logical link is estab- 
lished, however, network management dynamically computes the timeout 
period using various network parameters defined by the system manager 
using NCP and the SET EXECUTOR command. (See the DECnet/E System 
Manager’s Guide for details.) 
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This acknowledgment procedure between the two NSPs ensures that mes- 
sages sent over the logical link have been received, and that they were 
received in the same order they were sent. 


Each of the transmit queues for a logical link can hold up to eight messages. 
(This limit can be changed by the system manager to any number from one to 
eight to further protect system buffer space.) When one of the transmit queues 
for a logical link is filled with messages waiting for acknowledgment, further 
transmission of that type of message over the logical link is inhibited by the 
local NSP until one or more of the queued messages have been acknowledged 
by the remote NSP. 


An error is returned to the program if it issues a send request while the 
transmit queue for that message type is full. This condition is temporary. 
When the condition clears, send requests are again allowed for that message 
type. A program getting such an error on a send request should simply wait a 
short time (1 to 5 seconds) and retry the send request. 


The state of the transmit queues also affects the sending of Disconnect Mes- 
sages. If any messages are waiting for acknowledgment in the Data or Inter- 
rupt/Link Service transmit queue, a Send Disconnect Message call for that 
logical link will not be allowed and will result in an error. Thus, a program 
sending a successful Disconnect Message can assume that all previously sent 
messages have been received and acknowledged by the remote NSP. A Link 
Abort Message for that logical link will be allowed, however, and any mes- 
sages waiting in the transmit queues will be discarded. 


Figure 4-4 illustrates transmit queue flow control. PROGA has established 
two logical links, and PROGB and PROGC have each established one logical 
link. Each logical link has its own Data and Interrupt/Link Service Message 
transmit queues. PROGA issues a Send Network Data Message system call. 
The message goes to the Data Transmit Queue for that logical link and is also 
queued for transmission by the communication hardware. At the device driver 
level, all network messages (both data and control messages) await transmis- 
sion over the physical line. 


PROGB is shown trying to send a Network Interrupt Message. The Inter- 
rupt/Link Service transmit queue for that link is full, however, so NSP returns 
an error on the send. PROGC issues a Disconnect Message for its logical link. 
Since messages are still waiting for acknowledgment in the transmit queues, 
the Disconnect Message is not allowed and an error is returned. (Sending a 
Link Abort Message would have broken the link but the messages would have 
been discarded.) 
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Figure 44: How Transmit Queue Flow Control Affects a DECnet/E 
Program 
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4.2.2 Backpressure Flow Control 


NSP at the remote node can inhibit the local program from sending Network 
Data Messages over a logical link. The reasons for this blocking can vary from 
system to system: lack of system buffer space, system load, or some similar 
condition. This type of flow control, whereby the remote NSP can inhibit 
message flow from the local program, is known as backpressure. 


When the remote NSP receives a Network Data Message that it cannot pro- 
cess, it returns a negative acknowledgment (NAK) for the message, along with 
an error code informing the local NSP that data message flow to the remote 
program is being inhibited on the link over which the message was sent. The 
local NSP then inhibits transmission of Network Data Messages over the 
indicated logical link until further notice is received from the remote NSP. 
(Note that the local program can still receive messages over the logical link.) 
When the remote NSP informs the local NSP that the backpressure condition 
has cleared, the local NSP retransmits the message that was previously 
NAKed and reenables transmission of Network Data Messages over the log- 
ical link. 


If the backpressure condition clears before the local program attempts another 
send over the link, the program is not informed that the conditon occurred. 
However, if the program attempts to send another Network Data Message 
while transmission on the link is still inhibited, the local NSP returns an error 
to the program (see A, in Figure 4-5). When the condition clears, the local 
NSP delivers a Link Service Message to the program, informing it that trans- 
mission of Network Data Messages is again allowed for the indicated logical 
link (see B, in Figure 4-5). This Link Service Message is delivered to the local 
program on a Receive call when the queue of pending messages is empty. 


Note that the remote NSP enforces flow control for specific logical links, not 
for the entire node. 


From the reverse viewpoint, the local NSP will inhibit incoming data mes- 
sages on a logical link when a Network Data Message is received from a 
remote program over the link and the pending message queue of the intended 
receiver is full. (Remember that the local program itself limits the size of its 
pending message queue in its Declare Receiver call.) The local NSP informs 
the remote NSP that incoming data message flow has been inhibited by 
sending a message to the remote system. 


Under these conditions, the Network Data Message is not queued for the local 
program, but is NAKed by the local NSP. This forces the remote NSP to 
retransmit the message after flow is reenabled. Any data messages already 
transmitted by the remote node will also be NAKed by the local NSP. 


Furthermore, the local NSP marks all other logical links on the Receiver ID 
Block to be turned off if any Network Data Messages are received on those 
links. However, no message is sent to the remote system unless a Network 
Data Message is received on one of these links before the restriction is lifted. 
(Note that, while the local NSP no longer accepts incoming messages, the 
local program can still transmit.) 
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When the local program empties its pending message queue, any links that 
were actually turned off are turned back on and a message is sent to the 
remote NSP to reenable transmission. Those links that were merely flagged to 
be turned off are restored to normal operation, but no message is sent to the 


remote system. 


A. Remote node backpressures a link off 
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B. Remote node clears backpressured link, local program notified on receive 
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Figure 4-5: How Backpressure Flow Control Affects a DECnet/E 
Program as a Transmitter 
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4.2.3 Program-Regulated Flow Control 


During the connection sequence that establishes a logical link, each program 
must select one of the following three flow control options to regulate in- 
coming data over the link: 


e Segment flow control. The program requests data from the remote pro- 
gram by indicating how many segments it will accept at any given time. A 
segment is defined as the amount of user data transferred in one Network 
Data Message. The maximum size of a segment is determined by the receive 
maximum established in the Connect Initiate or Connect Confirm Message. 
The sending program is not required to use this maximum, however, and 
can, in fact, send smaller segments. Note also that segments transmitted 
and received by the same program are not necessarily equal in size. 


Logical message flow control. The program requests data from the re- 
mote program by indicating how many logical messages it will accept at any 
given time. A logical message can consist of one or more data segments. 
Control flags, included as part of a Network Data Message, indicate 
whether the data segment is the beginning, middle, end, or sole segment of a 
logical message. 


No active flow control. The program sets no limits on the rate at which 
messages can be sent to it over a logical link. 


If the program selects segment flow control or logical message flow control, the 
remote NSP will not send Network Data Messages over the link until the local 
program requests such transmission. Requests are made by sending a Link 
Service Message requesting a specific number of segments or logical messages. 


If the program selects the third option, no active flow control, no Link Service 
Messages can be sent except those requesting Interrupt Messages. Network 
Data Messages will be transmitted by the remote NSP as the remote program 
sends them, subject to backpressure. 


Flow control selection is independent at both ends of the logical link. That is, 
the remote and local programs need not select the same type of flow control. 
The option selected by the remote program, however, affects how the local 
program can send Network Data Messages. Therefore, the following discus- 
sion of flow control is presented from two viewpoints: 


1. How the option selected by the local program affects incoming Network 
Data Messages 


2. How the option selected by the remote program affects the way the local 
program sends Network Data Messages 


Flow Control on Incoming Data 


If the local program selects logical message flow control in the Connect Ini- 
tiate or Connect Confirm Message establishing a logical link, the local pro- 
gram must request data from the remote program by sending Link Service 
Messages specifying the number of logical messages to be transmitted. 
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When the Send Link Service Message call is issued, the local NSP adds the 
value specified to a message counter maintained for the link. The local NSP 
also sends the information on to the remote NSP. The remote NSP likewise 
adds the value specified to a message counter it maintains for the link. Thus 
both NSPs count the outstanding message requests. Each time the remote 
NSP sends the end segment of a logical message, it decrements the message 
counter. When the counter reaches zero, the remote NSP will inhibit trans- 
mission until the local program sends another Link Service Message speci- 
fying another value to add to the message counter. 


The local NSP uses its message counter as a protective measure. Each time it 
receives a data segment with the end-of-logical-message flag set, it decre- 
ments the message counter. When the counter reaches zero, the local NSP no 
longer accepts data segments over the link. Should the remote NSP send a 
segment while the local NSP’s counter is zero, the message is discarded and 
the link is aborted. The local NSP places a Link Abort Message in the local 
program’s queue of pending messages and sends a Link Abort Message to the 
remote NSP. (This situation is a protocol violation and should not occur with 
correct NSP operation.) 


When the local program selects segment flow control in the Connect Initiate 
or Connect Confirm Message, the local and remote NSP maintain segment 
counters for the logical link. The remote program can still send segments with 
the logical message control flags set for the local program to process inter- 
nally, but the counters maintained by NSP are kept for data segments sent, 
not for logical messages. Data is requested by sending a Link Service Message 
indicating the maximum number of segments to be sent. The local and remote 
NSPs add this value to their data segment counters and then decrement the 
counters as the remote program sends segments. When the data segment 
counter reaches zero, transmission over the logical link is suspended until 
another Link Service Message increments the count. 


When no active flow control is requested in the Connect Initiate or Connect 
Confirm Message, segments from the remote program can be transmitted over 
the logical link without being requested by the local program. The local and 
remote NSPs do not keep counters to regulate data sent and Link Service calls 
are not used to request transmission of data. Data Message flow can still be 
restricted by backpressure, however. 


Flow Control on Outgoing Data 


When the remote program specifies a flow control option in its Connect Ini- 
tiate or Connect Confirm Message establishing the logical link, the local NSP 
notes the option and establishes the appropriate counter. The counter is in- 
creased when a request for data is received from the remote system or pro- 
gram. If the remote program requested segment flow control, the counter is 
decremented by one each time the local program issues a Send Network Data 
Message call. If the remote program requested logical message flow control, 
the message counter is decremented by one each time a Network Data Mes- 
sage is sent that is flagged as the end data segment of a logical message. 
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When the counter equals zero, the local NSP inhibits further transmission of 
Network Data Messages over the logical link, returning an error if the local 
program tries to do so. In this circumstance, the local NSP delivers a Link 
Service Message to the local program when the condition clears and the 
pending message queue is empty. A Link Service Message is not delivered, 
however, if the local program did not attempt to send a Network Data Mes- 
sage while the request count was zero. 


This process is illustrated in Figure 4-6. The remote program has requested 
segment flow control. First, the remote program requests two segments (see A, 
in Figure 4-6). The segment counter for the remote program is incremented, 
but since PROGA has not had transmission inhibited, no Link Service Mes- 
sage is queued. The local program issues three Send Network Data Message 
calls (see B, in Figure 4-6). The segment counter is decremented to one with 
the first send, and to zero with the second send. The third send, while the 
counter is zero, results in an error. When the remote program receives and 
processes its two segments, it asks for two more segments (see C, in Figure 
4-6). The segment counter is incremented from 0 to 2, reenabling data sends. 
Since PROGA attempted a send that failed, a Link Service Message is deliv- 
ered to PROGA to indicate that data flow over the link has been reenabled. 
The Link Service Message is delivered to PROGA when it executes a Receive 
call when the pending message queue is empty. 


4.2.4 Interrupt Message Flow Control 


The transmission of Interrupt Messages over a logical link is subject to flow 
control by a request count mechanism. This mechanism is controlled by either 
the remote NSP or the remote program, depending on the particular DECnet 
implementation. 


All logical links are initiated with an outstanding Interrupt Message request 
count of one from the remote system. If the local program sends an Interrupt 
Message over the logical link, this count is decremented to zero. The local 
NSP does not allow another Interrupt Message to be sent over this logical link 
until the remote NSP or remote program sends a Link Service Message, 
incrementing the request count. An attempt by the local program to send an 
Interrupt Message while the counter is zero will result in an error. 


Once the request count is incremented by the remote system or program, the 
local NSP reenables Interrupt Message flow. If the local program has tried to 
send an Interrupt Message while the count was zero, NSP notifies the local 
program with a Link Service Message that Interrupt Messages can again be 
sent over this logical link. This Link Service Message is delivered to the local 
program on a Receive call when the pending message queue is empty. If the 
local program has not tried to send an Interrupt Message over the link while 
flow was disabled, no Link Service Message is delivered. 


From the reverse viewpoint, all DECnet/E logical links are initiated with an 
outstanding request for one Interrupt Message. If the remote program sends 
an Interrupt Message over the link, the iocal NSP decrements this count to 
zero. No further Interrupt Messages are accepted until the local program 
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A. Remote program requests two segments 
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C. Remote program requests two segments, local program notified on receive 
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requests one by sending a Link Service Message to increment the count. This 
also increments the request counter at the remote end and thus allows the 
remote program to send an Interrupt Message if it so desires. DECnet/E NSP 
does not allow the local program to request an Interrupt Message for a logical 
link unless a previous Interrupt Message on the link has been received. 


In DECnet/E, only one Interrupt Message can be requested on a logical link at 
any one time. That is, the request count is either zero or one. If a program 
tries to issue a Link Service Message requesting an Interrupt Message on a 
link when the request count is already one, the Link Service Message will 
result in an error. 


Figure 4-7 illustrates Interrupt Message flow control for a DECnet/E receiver. 
The remote program sends an Interrupt Message over a logical link (see A, in 
Figure 4-7). The local NSP decrements the Interrupt Message counter to zero 
and does not accept further Interrupt Messages over this link. The remote 
NSP also decrements its own counter and inhibits further Interrupt Messages 
from being sent. The local NSP maintains its counter as a safeguard measure. 
The local program sends a Link Service Message requesting one Interrupt 
Message over this logical link (see B, in Figure 4-7). The local NSP incre- 
ments its counter and tells the remote NSP to reenable Interrupt Messages 
over the link. The local program must receive the first Interrupt Message 
before the Link Service Message can be sent. 


4.2.5 Programming Hints for Flow Control 


A DECnet/E program can be prevented from transmitting for a number of 
reasons: 


1. No buffer space is available at the local node. (Prohibits sending of all 
message types.) 


2. The Data transmit queue is full. (Prohibits sending of Data Messages.) 


3. The Interrupt/Link Service transmit queue is full. (Prohibits sending of 
Interrupt and Link Service Messages. ) 


4. Message flow over the link has been inhibited by the remote system be- 
cause of a backpressure condition. (Prohibits sending of Data Messages.) 


5. No requests are outstanding for segments or logical messages from the 
remote program. (Prohibits sending of Data Messages.) 


6. No requests are outstanding for Interrupt Messages. (Prohibits sending of 
Interrupt Messages.) 


The first three conditions indicate congestion at the local node. They are 
temporary and no notification is given to the program when the condition 
clears. When one of these errors occurs on a send call, the program should 
simply reissue the call after a short delay of one to five seconds. 


The last three conditions, however, indicate congestion at the remote node. 
Since there is no way to predict how long it can take for one of these condi- 
tions to clear, the local NSP does not allow further sends of Data or Interrupt 
Messages until the remote system indicates that the condition has cleared. 
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A. Remote program sends an Interrupt Message over a logical link 
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8 Local program reenabies interrupts for the link (allowed only when previous Interrupt Message for this logical link nas been received) 
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Figure 4-7: How Interrupt Message Flow Control Affects a DECnet/E 
Program as a Receiver 
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When sending is blocked for one of these last three conditions, any attempt to 
send a message by the local program results in an error. The program can still 
receive messages, however. If an attempt to send a message resulted in an 
error in this fashion, NSP notifies the program when the condition clears. It 
does this by delivering a Link Service Message to the program when the 
program issues a Receive call and the pending message queue is empty. No 
notification is given if the local program did not try to send. 


Thus a program whose main function is to transmit data can be designed to 
send data over a logical link until transmission is blocked by one of the last 
three conditions. When sending is inhibited, the program can issue Receive 
calls to process all pending messages. When the pending message queue is 
empty and all conditions that block flow have cleared, a Link Service Message 
is delivered on a Receive call, giving current status information on flow con- 
trol for the logical link. (If more than one logical link has been blocked, 
Receive calls should be issued for all links until no messages are returned, 
since link service information can also be available on the other links.) 


A program whose main function is to receive data is concerned with keeping 
the pending message queue emptied so that the queue does not fill and cause 
the local NSP to inhibit incoming message flow over the program’s logical 
links. The Receive call with sleep can be used effectively by such a program so 
that it will be notified when a message is delivered to the queue. In this case, a 
second Receive call must be issued to retrieve the message. 


An interactive program can choose between these mostly-send and mostly- 
receive approaches, according to the requirements of the application. A pro- 
gram can also take advantage of the link status information that can be 
returned after sending Network Data, Interrupt, and Link Service Messages 
to regulate send and receive requests. The link status information returned is 
in the same format as a received Link Service Message. 
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Chapter 5 
Network Programming in FORTRAN 


This chapter presents the specific calls, along with detailed formats, used to 
access the DECnet/E message services in the FORTRAN programming lan- 
guage. 


5.1 Programming Background 


To use the RSTS/E message services in FORTRAN, you code subroutine calls 
with the CALL statement. The calls reference external MACRO subroutines, 
stored in the system library, that must be linked to your compiled object 
module. Thus, the process involves coding, compiling, and linking. These 
aspects of using DECnet/E in FORTRAN are described briefly in following 
subsections. Specific call formats are given in Sections 5.2 - 5.7. 


5.1.1 Coding 

The general form of the message calls in FORTRAN is: 
CALL name (arg!, arg2, ...) 

where 


name is the name of one of the twelve subroutines available for me 
services. Each subroutine processes a call at execution time by . 
cuting the following steps: 


1. Checking for the proper number of arguments in the call. 


2. Translating the call and arguments into the form recognizable to 
the RSTS/E monitor. 


3. Passing control to the RSTS/E monitor. (In DECnet/E systems. 
NSP is part of the RSTS/E monitor.) 


NSP processes the request and returns control to the user program. If 
an error occurs, NSP returns an error value to an integer variable 
defined as an argument in each call. 


5-1 


5-2 


arg... is the argument list for the particular call. The arguments are of two 
categories: input arguments and output arguments. 


Input Arguments 


Input arguments are those passed from your program to the DECnet/E 
MACRO subroutine. If the discussion of the argument calls for an integer 
value, you can specify any valid INTEGER*2 or INTEGER“4 variable, array 
element, expression, or constant for the argument. Since no DECnet integer 
argument ever exceeds 32767, however, there is no particular reason for you to 
use INTEGER*4 values; they are unnecessary and require an extra word of 
storage. 


If the discussion of the argument calls for a string, you can specify an alpha- 
numeric literal ("LITERAL’), a Hollerith constant (THCONSTANT), or a 
byte array containing the desired ASCII characters. 


If the discussion of the argument calls for the starting address of a buffer, you 
can specify any valid FORTRAN variable, array, or array element. The con- 
tents of the buffer can, in some cases, require special formatting on your part. 
The Send Connect Initiate Message call, for example, requires that you set up 
a Connect Data Block of 120 bytes. Some of the fields in the Connect Data 
Block can contain byte values ranging from 0 to 255. Please note that you can 
set LOGICAL*1 values within this range with the normal replacement state- 
ment. For example, the following sequence will work. If CDB(10) were used in 
some arithmetic calculation, however, it would be treated as -1. 


LOGICAL#1 COB( 120) 


COB(10) = .255 


Output Arguments 


Output arguments are those to which values are returned by the DECnet/E 
MACRO subroutine. There are only two possibilities: an error code returned 
as an integer and the starting address of a buffer containing returned informa- 
tion. 


If the value returned is an integer, the argument must be an INTEGER*2 
variable or array element. 


If the argument specifies a starting address of a buffer containing returned 
information, it can be any valid FORTRAN array, variable, or array element. 
In some cases, the buffer will contain status information. Tips for accessing 


‘this information follow. 


Tips for Returned Status Information 


The Receive call and three send calls (send Network Data, Interrupt, and 
Link Service) return status and control information to a 40-byte user buffer. 
Some of this information consists of numeric byte values that, in DECnet 
terms, have values from 0 through 255. This differs from the FORTRAN 
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treatment of numeric bytes as signed values ranging from -128 through +127. 
The easiest way to use these values in arithmetic conversions and comparisons 
is to convert them to positive integer values. A sample technique follows. 


LOGICAL#1i A( a0) 
LOGICAL#1 A2(2 +40) 
INTEGER 1A2(40) 


EQUIVALENCE (A2(1i+1)*TA2(1)) 
pO 20 121,40 
20 AZ(2+1) = 0 


. 


’ 
(call that returns status information to buffer A) 
. 


pO 4000 12140 
4000 AZ(1+I) = ACT) 


The LOGICAL*1 array A is the buffer to which the 40-byte status information 
is returned. A2 is a two-dimensional byte array mapped to the one-dimen- 
sional integer array IA2 with an EQUIVALENCE statement. Since two-di- 
mensional arrays in FORTRAN are stored by column, the first DO loop will 
set the high byte of each word of integer array IA2 to zero. The second DO 
loop will set the low byte of each word to the byte values in array A. The 


elements of array IA2 will then be positive integer values corresponding to the 
elements of array A. 


Note that not all the status information returned needs to be used in this way. 
Some values are signed bytes that can be directly referenced from array A in 
the previous example. Some are returned as integer values to which integer 
variable names can be directly assigned with an EQUIVALENCE statement. 


5.1.2 Compiling 


You can compile FORTRAN source code that includes DECnet subroutine 
calls with either one of two FORTRAN-IV compilers available on RSTS/E 
systems: the FORTRAN compiler (for code to be run under the RT11 Run- 
Time System) and the F4P (FORTRAN-IV-PLUS) compiler (for code to be 
run under the RSX Run-Time System). 

Complete instructions on how to compile using the FORTRAN compiler are 
given in the RT-11/RSTS/E F' ORTRAN IV User’s Guide. A typical sequence 
is as follows: 

RUN $FORTRAN 


sobjfile »lstfile=srcfile 
*¥°Z 


Ready 


Similarly, a typical compilation sequence for the F4P compiler is as follows: 
RUN $F4P 

FOP >objfile »lstfile=srcfile 

FaP>°Z 


Ready 
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5.1.3 Linking 


As with the compilers, two linkers are available on RSTS/E systems. Use 
LINK with object modules produced by the FORTRAN compiler. LINK re- 
solves references to the message subroutines from the system library 
($SYSLIB.OBJ). LINK is described in detail in the RSTS/E FORTRAN IV 
Utilities Manual. A typical link operation follows: 


RUN $LINK 
+ binfile »mapfile=objfile/F 
HAZ 


Ready 


To link object modules produced by F4P, use the RSTS/E Task Builder 
(TKB). The Task Builder will automatically resolve references to the message 
subroutines from the system library (LB:SYSLIB.OLB). The Task Builder is 
described in the RSTS/E Task Builder Reference Manual. A typical link 
operation with TKB follows: 


RUN $TKB 

TKB > binfile »mapfile=objfile »LB:F4POTS/LB 
TKB?// 

TKB?°Z 


Ready 


Network Programming in FORTRAN 


Cc 5.2 Declare Receiver (MDCL) — Privileged (Local and DECnet) 


The MDCL call must be executed before a program can receive any messages 
or send any network messages. (Local messages can be sent without first 
executing this call.) The call defines an identifying object type or name (or 
both) and any restrictions on incoming messages. NSP associates this infor- 
mation with the RSTS/E job number, setting up a Receiver ID Block for the 
job as described in Section 3.2.3. Only one MDCL call can be in effect at a 
time for a particular job. It remains in effect until a MREM call (Remove 
Receiver) is executed for the job. 


FORTRAN Call Format: 
CALL MDCL(errval,name,objtyp,access, bmax,mmax,|max) 


Argument Descriptions: 


¢ , errval 


The errval argument must be an integer variable or array element. This vari- 
able is set to zero if the MDCL call succeeds. If an error occurs, errval is set to 
one of the error codes listed under “Possible Errors” at the end of this section. 


name 


The logical name is a string consisting of one to six characters. Valid charac- 

ters are uppercase alphanumerics and the special characters “$” (dollar sign), 

“ (period), and “_” (underline). If less than six characters are used, the 
Cc name must be left-justified in the string and the remaining bytes must be 
filled with spaces. Leading or embedded spaces are invalid. If no name is to be 

specified (that is, the logical name is null), the string should contain 6 spaces. 


The name is used to identify the calling program for queuing messages from 
local or network programs. Local programs can address the calling program by 
the logical name. Network programs can use either the logical name or the 
object type code, if one is declared. 


For local or network programs to access the calling program by logical name, 

= the name must be nonnull and unique to the node. That is, only one program 
at the node can declare its identity with that name at any given time. NSP 
uses the logical name to identify the calling program for queuing messages 
from local or network programs. If the logical name is null, only network 
access by object type is allowed. (See the following discussion of logical name, 
objtyp, and access.) 


objtyp 


This integer value specifies the object type code, another form of network 
addressing. As discussed in Section 3.2.1, the object type code defines some 
service the calling program performs. If the program issuing the MDCL call is 
addressed by object code alone (name is null and access indicates network | 
access only), multiple copies can execute at the same time in the RSTS/E 
environment. Unlike the logical name, the object type code need not be 
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unique within the node — multiple copies of a program can declare their 
identity with the same type code simultaneously. If name is null, objtyp 
cannot be zero. (Network addressing is discussed in detail in Section 4.1.) 


Acceptable values for the object type code range from 0 through 255. The 
value 0 indicates that other programs in the network will never address the 
calling program by object type code. The range from 1 to 127 is reserved for 
DECnet use (see Appendix A). The range from 128 to 255 is available for 
definition and use by a network installation. 


access 


This integer contains the sum of five bit values (/ +p +n +0 + s) that are 
used to determine access to the declaring program and to modify certain 
aspects of the message operations. 


Three of these bit values (J, p, and n) limit the types of senders that can queue 
messages for the calling program. They do not limit the messages that the 
program can send. 


If | = 0, messages from local senders will not be queued for the calling pro- 
gram. (Local senders who use the network functions are considered network 
senders in this context.) If / = 1, messages from local senders will be queued. 


If p = 0, incoming messages from both local privileged and nonprivileged 
senders will be queued for the calling program. If p = 2, incoming messages 
from local senders will be queued only if the sender is privileged. (This bit is 
ignored if / = 0, that is, if no local senders are allowed.) 


If n = 0, incoming requests for logical links are rejected by NSP. If n = 4, 
incoming Connect Initiate Messages are passed on to the receiver, subject to 
the declared link maximum (/mazx). In this case, the program must provide its 
own protection from unauthorized access, if desired. 


Table 5-1 summarizes the /, p, and n values for access. 


Table 5-1: Types of Receiver Access 


Access Code Network Local Senders Local Senders 
(Il+p+n) Logical Links Privileged Allowed 

0 no no no 

1 no no yes 

2 no no no 

3 no yes yes 

4 yes no no 

5 yes no yes 

6 yes no no 

7 yes yes yes 
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Bit value o is used to regulate single-link programs, modifying the function of 
the program’s declared link maximum (Imax). If o = 0, incoming requests for 
logical links do not affect the link maximum. If 0 = 8, however, after queuing 
an incoming Connect Initiate Message to the receiver, NSP sets the program’s 
link maximum to zero, inhibiting all further incoming connect requests. This, 
in effect, modifies the meaning of the link maximum from “‘one link at a 
time” to ‘‘one link per program execution.” 


By setting this “one-shot” value to 8, a program prevents the possibility that 
NSP will queue a Connect Initiate Message for it after its one logical link is 
disconnected and before it issues a Remove Receiver call. 


The DECnet/E FAL utility, for example, sets the one-shot value to 8 and 
declares a link maximum of 1. Once FAL is started as the result of an in- 
coming request from a remote NFT utility, NSP queues the Connect Initiate 
_ Message and zeros the link maximum. Thus, there is no possibility that 
another incoming Connect Initiate Message could be queued for that copy 
between the time that NFT breaks the first link and the time that FAL issues 
its Remove Receiver call. This ensures that each incoming connect request 
starts a new copy of FAL. 


Bit value s is used to modify the function of the RSTS/E conditional Sleep 
monitor call. If s = 0, any unreceived messages queued for the program will 
block the execution of a conditional Sleep call. This is the normal RSTS/E 
function. If s = 16, however, the RSTS/E monitor will not check the program’s 
message queue when determining whether or not it should in fact suspend 
program execution. Several other conditions (such as a delimiter received on 
an open terminal) can still block the sleep but a pending message will not. 


logical name, objtyp, and access 


NSP checks the name, objtyp, and access arguments to ensure that they are 
consistent. For example, a null logical name and an access code allowing local 
senders are inconsistent, since local senders can address the program by log- 
ical name. NSP checks these arguments as shown in Table 5-2. If the argu- 
ments are invalid, NSP returns an error code of 18 in the errval argument. If 
the arguments are valid, NSP allocates a small buffer to hold the information 
passed. If no buffers are available, the call fails with errval = 4. A retry may 
succeed. 


Table 5-2: System Validation of Name, Object, and Access Parameters 


Access Code Senders Object 

(i+p+n) Permitted Type Logical Name 

0,2 None Ignored Ignored. 

1,3 Local only Ignored Must be nonnull and unique. 

4,6 Network only Zero Must be nonnull and unique. 
Nonzero If name is null (at least one 


leading binary zero byte), the only 
access permitted is by object type. 
Multiple copies of the program 
can coexist. 

(continued on next page) 
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Table 5-2 (cont.): System Validation of Name, Object, and Access 
Parameters 


Access Code Senders Object 
(N%+p%+I%) Permitted Type Logical Name 


If name is nonnull, it must be 
unique at the local node. Network 
senders can refer to the calling 
program by name or by object 
type. Only one copy of the pro- 
gram using this logical name can 
execute at any given time. 


5,7 Network/Local Any value Must be nonnull and unique so 
that local senders can refer to the 
calling program by logical name. 
Network senders can use the log- 
ical name or object type (if objtyp 
# 0). Only one copy of the pro- 
gram using this logical name can 
execute at any given time. 


bmax 


Until a Receive call (MRCV) is executed, a pending message occupies system 
buffer space. One 16-word buffer from the monitor’s buffer pool is used for 
user- or DECnet-defined parameters and other system-specific information. 
Additional buffer space for the message data is usually allocated from the 
extended buffer pool. If an extended pool does not exist, or no space is avail- 
able there, the monitor’s buffer pvol is used. 


Because the monitor pool is a critical system resource, the program must set a 
limit on the amount of space to be used on its behalf. The integer argument 
bmax sets a limit (1 to 32767 bytes) on the total monitor pool space to be used 
for the user data portion of messages. 


When this buffer maximum is exceeded, Local Data Messages are no longer 
queued for the calling program. NSP returns an error to any local program 
that tries to send a Local Data Message at this point. Network messages are 
queued regardless of the declared buffer maximum but any monitor pool 
space used will be counted against the maximum. 


A zero or negative value indicates that the monitor’s buffer pool is not to be 
used for the user data portion of pending Local Data Messages. 


mmax 


The message maximum (mmax), an integer value ranging from 0 to 255, 
limits the number of messages that will be queued for the calling program. 


NSP keeps a count of the total number of messages queued for each declared 
receiver. When one of these counters equals or exceeds the maximum set by a 
receiver: 


1. Incoming Local Data Messages are no longer queued for the receiving 
program. An error is returned to the local sender. 
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2. Incoming Connect Initiate Messages cause NSP to determine whether 
another copy of the program can be started automatically (see Section 
4.1.2). If not, NSP rejects the connection and the Connect Initiate Mes- 
sage is not queued. A Connect Reject Message is returned to the sender. 


3. An incoming Network Data Message causes NSP to inhibit incoming data 
messages on that particular logical link and to negatively acknowledge 
(NAK) the message. This forces the remote system to retransmit when 


flow is reenabled. (See Section 4.2.2 for further details on backpressure 
flow control.) 


Imax 


The link maximum (Imax), an integer value ranging from 0 to 63, limits the 
number of incoming requests for logical links for the declaring program. If the 
number of links currently active is greater than or equal to Imax when a 
remote Connect Initiate Message is received for the calling program, the local 
NSP determines whether another copy of the program can be started auto- 
matically (see Section 4.1.2). If not, NSP rejects the connection and the 
Connect Initiate Message is not queued. A Connect Reject Message is re- 
turned to the sender. 


By declaring a small link maximum, a program can avoid the overhead of 
responding to remote Connect Initiate Messages when it is known beforehand 
that the program can only handle a limited number of logical links. 


A zero value for Imax has the same effect as setting n = 0 in the access 
argument. That is, NSP rejects all incoming requests for logical links to the 
calling program. The /max argument does not, however, limit the number of 
logical links initiated by the program. That is, it does not stop the program 
from sending Connect Initiate Messages. 


-Possible Errors: 


errval Error Text and Meaning 


1 BAD DIRECTORY ON DEVICE 


Network operations have been terminated due to an internal error. Notify the 
system manager. 


3 ACCOUNT OR DEVICE IN USE 


The calling job already exists in the system’s list of declared receivers. This error 
can indicate a logic error in the program or that a previous program running under 
the same job number failed to remove itself from the receiver list before termi- 
nating. In the latter case, a Remove Receiver call should be isssued, followed by 
another Declare Receiver call. (It is common practice to code a Remove Receiver 
call immediately before a Declare Receiver call.) 


4 NO ROOM FOR USER ON DEVICE 


There were no small buffers available to hold the arguments passed with the 
Declare Receiver call. Since the system’s use of small buffers is dynamic, a retry 
may succeed. 


(continued on next page) 
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errval Error Text and Meaning 


10 PROTECTION VIOLATION 
The calling program must be privileged at the time the Declare Receiver call is 
executed. 

16 NAME OR ACCOUNT NOW EXISTS 


The logical name specified is being used by another job. 
18 ILLEGAL SYS() USAGE 


The parameters specified are inconsistent. See the discussion of logical name, 
object, and access. 


Example: 


The following example shows a Declare Receiver call allowing both network 
and local access. Both a logical name (BUS) and an object type code (142) are 
specified. The buffer maximum is set to 512 and the message maximum is set 
to 5. No more than 512 bytes of user message data from incoming Local Data 
Messages will be stored in monitor pool space. If more than 5 messages accu- 
mulate for the program, an incoming request for a connection will cause NSP 
to check to determine whether another copy of the program can be started 
automatically. If nots NSP will reject the link. Incoming data messages at this 
point will-also cause NSP to inhibit incoming message flow on all the pro- 
gram’s logical links because of the backpressure condition. The link max- 
imum is set to 2. When the program has established two logical links, an 
incoming Connect Initiate Message will cause NSP to check to determine 
whether another copy of the program can be started. If not, NSP will reject 
the link. 


INTEGER ERRVAL ,OBJTYP »ACCESS »BMAX »MMAX +L MAX 


OBJTYP 
ACCESS 
BMAX = 
MMAX = 
LMAX = 2 

CALL MOCL(ERRVAL »"BUS "+ OBJTYP ,ACCESS +BMAX »MMAXK »LMAX ) 
IF ERRVAL .NE. O THEN 1200 “me 


mann 
_ 
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Se 5.3 Remove Receiver (MREM) (Local and DECnet) 


The MREM call removes the specified job from the system’s list of declared 
receivers. All pending messages are discarded and any active logical links are 
aborted. This call should be executed at the completion of message pro- 
cessing. This prevents unwanted messages from accumulating in the queue of 
pending messages. 


Privileged programs can remove other RSTS/E jobs with this call, although 
normally only system utility programs would do this. 


FORTRAN Call Format: 
CALL MREM(errval,jobx2) 
Argument Descriptions: 


¢ errval 


The errval argument must be an integer variable name. This variable is set to 
zero if the MREM call succeeds. If an error occurs, errval is set to one of the 
error codes listed under “Possible Errors” at the end of this section. 


jobx2 


A zero value for jobx2 removes the calling job. Privileged programs can re- 
move another local RSTS/E job by specifying job number times two for this 


integer argument. 
C Possible Errors: 
errval Error Text and Meaning 
1 BAD DIRECTORY ON DEVICE 


Network operations have been terminated due to an internal error. Notify the 
system manager. 


( 10 PROTECTION VIOLATION 


The caller is nonprivileged and has attempted to remove another job (that is, 
jobx2 is nonzero). 


18 ILLEGAL SYS() USAGE 


The jobx2 argument was odd. Jobx2 must be zero to remove the calling program 
or job number times two to remove another job. . 


Example: 


The following example shows a typical Remove Receiver call removing the 
calling job from the system’s list of declared receivers. 


_INTEGER ERRVAL 


. 


( CALL MREM(ERRVAL +0) 
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5.4 Get Local Node Parameters (NTLN) (DECnet) 
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The NTLN call returns information to the calling program concerning the 
local node’s network parameters. Data returned includes the node’s name, 
address and alias (if any), and the default user’s account to be used when an 
incoming Connect Initiate Message does not specify accounting information. 
(See the DECnet/E System Manager’s Guide for a discussion of alias and 
Section 4.1.4 of this manual for a discussion of the default user’s account.) 


FORTRAN Call Format: 

CALL NTLN(errval, buffer, buflen, bufoff) 
Argument Descriptions: 

errval 


The errval argument must be an integer variable name. This variable is set to 
zero if the NTLN call succeeds. If an error occurs, errval is set to one of the 
error codes listed under ‘‘Possible Errors” at the end of this section. 


buffer 


This argument defines the starting address of the buffer to receive the local 
node information. If a nonzero offset is given (see bufoff), the offset is added to 
the starting address specified by buffer. When the NTLN call completes 
successfully, data is returned to the buffer in the following format: 


Bytes Contents 


0-5 Local node name, consisting of 1 to 6 uppercase, alphanumeric ASCII characters. 
The name contains at least one alphabetic character. A name shorter than 6 
characters is left-justified and padded to 6 characters with spaces. 


6-7 Local node address, ranging from 1 to 255. 


8-13 Local node alias, consisting of 1 to 6 uppercase, alphanumeric ASCII characters. 
The alias contains at least one alphabetic character. An alias shorter than 6 
characters is left-justified and padded to 6 characters with spaces. If no alias 1s 
defined, a field of 6 spaces is returned. 


14-15 Local default project-programmer number. Byte 14 = programmer number; byte 
15 = project number. If no default account is defined, both bytes are zero. 


bufien 


This integer argument defines the number of bytes to be returned to the buffer 
specified with buffer. If buflen is less than 16 bytes, the call returns only as 
much data as there is room for. For example, if buflen = 8 bytes, the call 
returns only the local node name and address. Sixteen bytes are required to 
receive all the local node parameters. 


bufoff 


This integer value defines an offset, in bytes, from the address specified in 
buffer. The value of bufoff is added to buffer to define the beginning address 
of the returned data. For example, if offset = 20, the returned data begins in 
byte 21 of the buffer. 
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byte 1 


20 {21 (buflen +20) 


returned data 


whole buffer 
NOTE 





The FORTRAN interface makes no checks for inconsistencies 
in the buffer, buflen, and bufoff values specified. A program 
could, for example, specify a buflen of 16 and a bufoff of 10. If 
the actual buffer, beginning at buffer was only 16 bytes long, 
the returned data would overwrite 10 bytes beyond the end of 
the buffer. 


Possible Errors: 


errval 


62 


Error Text and Meaning 


BAD DIRECTORY ON DEVICE 


Network operations have been terminated due to an internal error. Notify the 
system manager. 


NO RUN-TIME SYSTEM 


NSP has not been enabled. Normal DECnet calls cannot be executed until the 
system manager enables NSP. 


MISSING SPECIAL FEATURE 


DECnet was not installed at system generation time. The network functions 
cannot be executed. 


Example: 


The following example shows a NTLN call used to obtain all the local node 
parameters. The node name is to be stored in the LOGICAL*1 variable 
NAME; the address, in the integer variable ADDRSS; the node alias, in the 
LOGICAL *1 variable ALIAS; and the default project-programmer number, in 
the LOGICAL*1 variables PROJ and PROG. 


LOGICAL#1 BUFFER(16) »NAME(G) sALIAS(G) »PROJ»PROG 
INTEGER BUFLEN +BUFOFF »ADORSS rERRVAL 

EQUIVALENCE (BUFFER (1) »NAME(1)) »(BUFFER(7) »ADDRSS) 
EQUIVALENCE (BUFFER(9) sALIAS(1)) »(BUFFER(15) »PROG) 
EQUIVALENCE (BUFFER(16) »PROJ) 


. 


. 


BUFLEN = 16 


BUFOFF 


= 0 


CALL NTLN(ERRVAL »BUFFER »BUFLEN »BUFOFF ) 
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5.5 Log User Event (NTEV) — Privileged (DECnet) 
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The NTEV call permits a user-written program to queue an event to the 
system event processor for logging. Before the event is logged, it is time- 
stamped by the system, in the standard Network Information and Control 
Exchange (NICE) protocol format. The system manager can use the normal 
network management SET and CLEAR LOGGING commands to control the 
filtering of these events. Optional data can accompany a user event. 


NOTE 


This system call performs a highly specialized function which 
requires a great deal of special knowledge of DECnet and the 
DIGITAL Network Architecture (DNA). It is provided as a 
convenience for the sophisticated network user and is not in- 
tended for normal network programs. 


FORTRAN Call Format: 

CALL NTEV(errval,evmod,evcls,evtyp,entyp,enval, buffer, buflen. bufoff) 
Argument Descriptions: 

errval 


The errval argument must be an integer variable name. This variable is set to 
zero if the NTEV call succeeds. If an error occurs, errval is set to one of the 
error codes listed under ‘‘Possible Errors” at the end of this section. 


evmod 


This integer argument specifies what the system should do if it is unable to log 
the user evert due to lack of resources. If eumod is set to zero, the call 
terminates wi h a status return of NOROOM (errval = 4); the program can 
retry logging he event after a short delay. If eumod = 1, the system logs a 
“missed event” event message, and the call terminates with a successful 
statu:. (errval = 0). 


Note that in the second case, the user data is not logged. The system merely 
logs the fact that it has lost some unidentified data. This is identical to the 
procedure followed with DECnet internal events when the event queue is full 
or there are no more small buffers. 


. evcis 


This integer argument specifies the class of the user event to be logged. Events 
are divided into classes, according to the DNA layer from which they origi- 
nate. Classes 480 to 511 are reserved for customer-specific events. However, 
DECnet/E supports only class 480. Thus, evcls must be 480. 


evtyp 


This integer argument specifies the type of event within the class specified by 
evcls. The event type must be in the range of 0 to 31. 
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entyp 


This integer argument specifies the entity type with which the event is con- 
cerned. There are four entity types supported by DECnet/E, defined as fol- 
lows: 


-1 No specific entity 
0 Node 
1 Line 
3 Circuit 

enval 


This integer argument associates a value to the entity specified by the entyp 
argument. If the entity is a node, enval should be set to the node address. If 
the entity is a line or a circuit, enval should be set to the address of the Device 
Data Block (DDB) maintained for the device. 


buffer 


This argument defines the starting address of the buffer containing the op- 
tional user data to be processed with the event. If a nonzero offset is specified 
(see bufoff), the offset is added to the starting address of the buffer. 


If this data is included, it must be in NICE protocol format. Basically, this 
means that the data should be formatted in a 3-part field: a parameter type, a 
data type, and a parameter value. DECnet parameter types can be used if the 
event concerns a node, a circuit, or a line. In this case, the event logger will 
output standard descriptive text for the specific parameter. If a DECnet pa- 
rameter type is not used, parameter types in the range of 3900 to 4095 can be 
specified. (See the DIGITAL Network Architecture, Network Management - 
Functional Specification, Version 3.0.0, for further information on event defi- 
nitions and parameters.) 


Up to 200 bytes of data can be passed to the event logger for processing. 
buflen 


This integer value defines the number of bytes of data in the buffer specified 
with buffer. Up to 200 bytes of data can be passed. If no data is specified, 
buflen must be 0. 


bufoff 


This integer value defines an offset, in bytes, from the address specified in 
buffer. The value of bufoff is added to buffer to define the beginning address 
of the returned data. For example, if bufoff = 20, the data to be processed 
begins in byte 21 of the buffer. 


byte 1 20)21 (buflen+20) 


ee 


whole buffer 
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NOTE 


The FORTRAN interface makes no checks for inconsistencies 
in the buffer, buflen, and bufoff values specified. A program 
could, for example, specify a buflen of 16 and a bufoff of -100. 
Sixteen bytes of data would be processed, starting with the 
byte at buffer-100. 


Possible Errors: 


errval Error Text and Meaning 


1 BAD DIRECTORY ON DEVICE 


Network operations have been terminated due to an internal error. Notify the 
system manager. : 


4 NO ROOM FOR USER ON DEVICE 


The event queue is full or there are no small buffers available to hold the event. A 
retry may succeed. (This error is returned only if eumod = 0.) 


5 CAN’T FIND FILE OR ACCOUNT 

The event logger is not running. Have the system manager start the event logger. 
10 PROTECTION VIOLATION 

The calling program must be privileged at the time the NTEV call is issued 
18° ILLEGAL SYS() USAGE 


The parameters passed are either inconsistent or invalid. 
66 MISSING SPECIAL FEATURE 


DECnet was not installed at system generation time. The network funct 
cannot be executed. 
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Example: 


The following example illustrates the logging of a user event, class 480. and 
type 3. The entity is node number 135. The optional data passed for pro- 
cessing consists of an lla parameter number (2130) and value. A ‘‘missed 
event” is logged if the event itself cannot be. 


LOGICAL*1 DATBUF(30) »DATLEN 

INTEGER BUFOFF »BUFLEN +DATPRM rDATYAL 

INTEGER EVMOD »/EVTYP vEVCLS rENTYP sENVAL *ERRVAL 
EQUIVALENCE (DATBUF (7) »DATPRM) »(DATBUF (9) »DATLEN) 
EQUIVALENCE (DATBUF (10) »DATVAL) 


. 


BUFOFF 


= 6 
BUFLEN = 5 
DATPRM = 2130 
DATLEN = 2 
DATYVAL = 40960 
EYmMOD = 1 
EVTYP = 480 
EVCLS = 3 
ENTYP = 0 
ENYAL = 135 


CALL NTEV(ERRVAL »EVMOD »EYCLS /EVTYP ,ENTYP sENVAL + 
DATBUF »BUFLEN +BUFOFF ) 


The NTEV call in the previous example generates the following event mes- 
sage: , 


Event type 480.3 : 
Occurred 14-Dec-81 15:31:39-7 on node 135 (GROK) 

Node address 135 (GROK) 

Parameter #2130 = 40960 = 


Network Programming in FORTRAN 5-17 


5.6 Send Calls 
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There are nine separate send calls — one local and eight network. Each of 
these calls causes NSP to format a message that is then either queued to a 
local program or transmitted across the network to a remote program. 


5.6.1 Send Local Data Message (MSLD) (Local) 


The MSLD call sends up to 532 bytes of user data to another program on the 
local RSTS/E system. The other program must be a declared receiver of local 
messages. If the other program has declared that only privileged local senders 
are allowed, the calling program must be privileged or the MSLD will fail with 
an error. The receiving program is identified in the MSLD call either by its 
job number or by the logical name with which it declared itself a receiver. 


FORTRAN Call Format: _ 

CALL MSLD(errval,jobx2,name, buffer, buflen, bufoff,parptr,parlen) 
Argument Descriptions: 

errval 


The errval argument must be an integer variable name. This variable is set to 
zero if the MSLD call succeeds. If an error occurs, errval is set to one of the 
error codes listed under ‘‘Possible Errors’ at the end of this section. 


jobx2 


If jobx2 is zero, the message data is sent to the local program identified by the 
name argument. Otherwise the message data is sent to the program whose job 
number (times two) is equal to the value of jobx2. For example, if jobx2 = 8, 
the message is sent to job 4. . 


name 


The name argument identifies the intended local receiver when the jobx2 
argument = 0. The intended receiver must have declared its identity with this 
name in its Declare Receiver call. The name consists of one to six characters, 
left-justified and, if necessary, padded to six bytes with spaces. Valid charac- 
ters are uppercase alphanumerics and the special characters “*$’’ (dollar sign), 
“” (period), and ““_” (underline). Leading or embedded spaces are invalid. 


‘This field is ignored when jobx2 + 0. 


buffer 


This argument defines the starting address of a buffer containing the message 
data. If a nonzero offset is given (see bufoff), the offset is added to the starting 
address specified by the buffer argument. 


buflen 


This integer argument defines the number of bytes to be sent from the buffer. 
Possible values for buflen range from 0 through 512. 
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bufoff 


This integer value defines an offset, in bytes, from the address specified by the 
buffer argument. The value of bufoff is added to the Starting address of the 
buffer to define the beginning address of the message data to be sent. For 
example, if offset = 20, the user data begins in byte 21 of the buffer. 


byte 1 20)21 (buflen+20) 


user data 


whole buffer 
NOTE 


The FORTRAN interface makes no checks for inconsistencies 
in the buffer, buflen, and bufoff values specified. A program 
could, for example, specify a buflen of 512 and a bufoff of 1000. 
The MSLD call would send 512 bytes beginning at buffer+1000. 





parptr 


This argument defines the starting address of a buffer containing up to 20 
bytes of parameter message data to be sent to the local receiver. This data will 
be delivered separate from the message data in the buffer area. For example, a 
RSTS/E FORTRAN program doing a Receive call that returns a Local Data 
Message will receive the parameter data and the message data in two separate 
buffers defined in the Receive call. 


parien 


This integer value defines the number of bytes to be sent from the parameter 
area defined by parptr. The parlen value can range from 0 through 20. 


Possible Errors: 


errval Error Text and Meaning 


4 NO ROOM FOR USER ON DEVICE 


The number of pending messages for the intended local receiver is at its declared 
maximum. The sending program should try again later. If this error occurs repeat- 
edly, the receiver is not processing messages often enough. 


5 CAN’T FIND FILE.OR ACCOUNT 


The intended local receiver could not be located in the system’s list of declared — 
receivers. The receiving program must have declared itself a receiver (with a 
Declare Receiver call) before any data can be transmitted to it. 


10 PROTECTION VIOLATION 


Some access violation has occurred. Either the receiver does not allow any local 
senders or the sender is nonprivileged and the receiver allows only privileged 
senders. 


(continued on next page) 
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errval Error Text and Meaning 


18 ILLEGAL SYS() USAGE 
The value of jobx2 is odd. It must be equal to zero or to the receiver's job number 
times two. 

31 ILLEGAL BYTE COUNT FOR 1/0 


Either the bujlen value or the parlen value is invalid. The buflen argument can 
range from 0 through 512; the parlen argument can range from 0 through 20. 


32 NO BUFFER SPACE AVAILABLE 


System buffers are currently not available to store this message for the intended 
local receiver. A later retry may succeed. 


Example: 


The following example shows a local send to a program that has issued a 
Declare Receiver call with the logical name LOCAL. A total of 156 bytes are 
sent from array A. No parameter message data is sent. 


BYTE A( 156) 
INTEGER BUFLEN »BUFOFF »/ERRVAL 


+ 


BUFLEN = 156 
BUFOFF = 90 
CALL MSLO(ERRVAL»O,"LOCAL “»A»BUFLEN »BUFOFF 10 +0) 
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5.6.2 Send Connect Initiate Message (NTCI) (DECnet) 


The NTCI call is used to request a logical link to another program. The call 
establishes the user link address the calling program will use to refer to the 
link. The other program is identified with a Connect Data Block. Other argu- 
ments specify the flow control option and maximum amount of user data for 
received Network Data Messages. Up to 16 bytes of user data can be sent with 
the NTCI call. 


FORTRAN Call Format: 

CALL NTCl(errval,ula,llmod,rmax, buffer, buflen, bufoff) 
Argument Descriptions: 

errval 


The errval argument must be an integer variable name. This variable is set to 
zero if the NTCI call succeeds. If an error occurs, errval is set to one of the 
error codes listed under “Possible Errors” at the end of this section. 


ula 


The user link address (ula) is an integer value in the range of 1 to 255. Later 
calls to send and receive messages use this value to refer to the logical link 
(assuming that the link being requested by the’ NTCI call is accepted by the 
remote NSP and the remote program). 


The ula must be unique within the program at any given time. That is, one 
program cannot have two different logical links with the same ula at the same 
time. 


limod 


The integer value /lJmod indicates the type of flow control requested by the 
calling program to control incoming data from the remote program. Accept- 
able values and meanings are: 


0 No flow control 
1 Segment flow control 
2 Message flow control 


Flow control is described in detail in Chapter 4. Remember that each program 
on a logical link selects its own flow control. The l/mod value is the selection 
made by the calling program. If //mod is nonzero, the calling program must 
issue Link Service (NTLS) calls to request Network Data Messages from the 
other program. 


Network Programming in FORTRAN 5-21 


5-22 


rmax 


A program that has limited buffer space and is not designed to process large 
messages in small pieces can impose a limit on the-amount of user message 
data it is willing to receive on a logical link. The integer value rmax specifies 
this limit in bytes. 


The size of the receive buffers allocated by NSP will itself limit the amount of 
data that can be passed in a single Network Data Message. If the maximum 
size set for NSP by Network Management is not large enough to handle the 
receive maximum as specified in rmazx, the local NSP will alter the maximum 
to the smaller limit before forwarding the Connect Initiate Message to the 
remote node. If rmax = 0, NSP will supply the size of its receive buffers as a 
default value. (The calling program will be informed of any such change by a 
field in the Connect Confirm Message from the target program when the link 
is accepted.) 


The remote NSP uses this value to establish a transmit maximum for its end 
of the logical link. If the remote system is also a RSTS/E system, this transmit 
maximum is passed on to the remote program. The remote program must 
limit the amount of user message data it sends over the logical link according 
to this value. 


See the discussion of the buflen argument for the Receive call (MRCV) in 
Section 5.7 for a description of how to process large messages in small pieces. 


buffer 


This argument defines the starting address of a buffer containing the Connect 
Data Block and optional user message ‘data. If a nonzero offset is given (see 
bufoff), the offset is added to the starting address of the buffer. 


The Connect Data Block identifies the target program for the requested log- 
ical link. Figure 5-1 shows the format of the Connect Data Block. The fields 
within are described in Table 5-3. 


Up to 16 bytes of user data can follow the Connect Data Block. 
buflen 


This integer value defines the number of bytes to be sent. Since the Connect 
Data Block is 120 bytes long and the optional user data can be from 0 to 16 
bytes long, acceptable values for buflen range from 120 through 136. 


bufoff 


This integer value defines an offset, in bytes, from the start of the buffer from 
which the data is to be sent. The offset value is added to the starting address 
of the buffer to define where the Connect Data Block begins. For example, if 
bufoff = 20, the Connect Data Block begins in byte 21 of the buffer. 


byte 1 20| 21 140 141 


whole buffer 
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NOTE 


The FORTRAN interface makes no checks for inconsistencies 
in the buffer, buflen, and bufoff values specified. A program 
could, for example specify a buffer 100 bytes long, an offset of 
90 and a length of 136. In this case, 136 bytes would be sent: the 
last 80 bytes of the buffer and 56 bytes of whatever is beyond 


the buffer in memory. 
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Figure 5-1: Format of Connect Data Block on Send Connect Initiate 
Message 


Table 5-3: Format of Connect Data Block on Send Connect Initiate 
Message 


Bytes Content 


1-6 Remote Node. 1 to 6 uppercase, alphanumeric ASCII characters naming the 
remote node to which the Connect Initiate Message is to be sent. This name 
must contain at least one alphabetic character and names shorter than six 
characters must be left-justified and padded to six characters with spaces. 
Leading and embedded spaces are invalid. If no node name is specified (that is. 
the request is directed to a program at the local node), these 6 bytes contain 
spaces. 


(continued on next page) 
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Table 5-3 (cont.): Format of Connect Data Block on Send Connect 


7-26 


Initiate Message 


Remote Program. Identifies the remote program to which the Connect Initiate 
Message is directed as either an object type (general function) or a specific entity 
(program, task, or process). This identification is given in one of three formats: 


Format 0 
The remote program is identified by object type code alone. The fields are: 
Bytes Content 


7 Zero, to indicate a format 0 name. 
8 Object type code of the remote program. 
9-26 Zero (Not used). 


Format 1 
The remote program is identified by a descriptor. The fields are: 
Bytes Content 


7 One, to indicate a format 1 name. 

8 Normally zero. This byte should be zero unless the target DECnet 
system allows identification by both name and object type code on in- 
coming connect requests (DECnet/E does not). If nonzero, this byte is 
interpreted as the object type code of the remote program for which the 
Connect Initiate Message is intended. 

9 Reserved — must be zero. 

10 Length of descriptor, 0 to 16 bytes. Gives the number of characters to be 
interpreted as the program descriptor in the following field. 

11-26 Remote program descriptor (left-justified). For a DECnet/E. program, 
this is the logical name that the remote program defined in its Declare 
Receiver call. For other systems, it is the descriptor used to register the 
program for network operations. 


Format 2 


This format allows identification of the remote program by name or object type 
code and by the group and user codes under which the remote program is acces- 
sible on the remote system. (The group and user codes refer to what is called the 
project-programmer number on some DIGITAL systems, including RSTS/E. 
Other systems refer to these codes as the user identification code, or UIC.) 
DECnet/E systems use only the object type code or descriptor to find or start the 
target program for which a connect request is intended. The group and user codes 
are simply passed on to the target program for its own checking. Other DECnet 
systems may handle an incoming connect request in format 2 differently. 


The subfields are defined as follows: 
Bytes Content 


7 Two, to indicate a format 2 name. 

8 Object type code of the remote program, if applicable. If zero, the de- 
scriptor must be used. 

9 Reserved — must be zero. 

10 Length of descriptor, 0 to 12 bytes. Gives the number of characters to be, 


interpreted as the program descriptor in the following field (bytes 11-22). 
11-22 Remote program descriptor, if this is used instead of object type code. 
The descriptor should be left-justified in the field. 


(continued on next page) 
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Table 5-3 (cont.): Format of Connect Data Block on Send Connect 


27-46 


47-92 


Initiate Message 

Bytes Contents 

23-24 Remote group code. Binary value giving the group number under which 
the remote program is running or is to be started. Corresponds to the 
project number in a RSTS/E project-programmer number. This value is 
not used by DECnet/E systems but is simply passed on to the receiving 
program. 

95-26 Remote user code. Binary value giving the user number under which the 
remote program is running or is to be started. Corresponds to the pro- 
grammer number in a RSTS/E project-programmer number. This value 
is not used by DECnet/E systems but is simply passed on to the re- 
ceiving program. 


Local Program. This field is filled in by the local NSP using information that 
the local program specified in its Declare Receiver call. Any values passed by the 
user program in this area are ignored. 


The information is passed to the remote system in format 2, as described previ- 
ously. Byte 27 is filled in with a value of 2. Byte 29 is always zero. If the program 
declared its identity with an object code alone, the object code is passed in byte 
28 and bytes 30-42 are zero. If the program declared its identity with a logical 
name, or with a logical name and object type code, the local name is supplied in 
bytes 31-42 and byte 28 is zero. The length of the logical name is given in byte 
30. The project-programmer number under which the program is running is 
passed in bytes 43-46 as the group and user codes. The project number is in byte 
43; the programmer number is in byte 45. Both are in binary format. 


Access Control Fields. These bytes can be used to define the calling program’s 
access rights to the remote system or to the remote system’s services. The idea is 
analogous to logging in on the remote system. The most rigorous checking done in 
a normal log-in on DIGITAL systems involve user identification, password, and 
account number, so three fields are defined here for those items. However, overall 
DECnet design does not specifically require use of these fields at all, nor does it 
require that the fields be used as described. A DECnet/E system simply passes 
this information on to the receiving program. To determine what, if anything, a 
non-RSTS/E DECnet system requires in these fields, see the DECnet manual for 
that system. 


NOTE 


The DECnet/E utilities NFT and NETCPY, that use logical links 
to access remote files and devices, use these fields to establish the 
local terminal user’s right to access remote files and devices. Both 
utilities prompt the local user for log-in information to be used at 
the remote system and pass that information along in the Con- 
nect Data Block of the Connect Initiate Message. The remote 
FAL or receiving NETCPY checks this information before al- 
lowing the operation requested. . 


Bytes Content 


47 Reserved — must be zero. 
48 Length of user identification information specified in the next field, 0 to 
16 bytes. 


49-64 User Identification. This field identifies the person or program re- 
questing the logical link. In RSTS/E terms, the user ID is analogous to 
the project-programmer number used at log-in. This information need 
only be specified here if it is required by the remote system or program. 
If it is not required, the length (byte 48) should be set to zero. 


(continued on next page) 
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Table 5-3 (cont.): Format of Connect Data Block on Send Connect 


93-120 


Initiate Message 


65 Reserved — must be zero. 

66 Length of password information specified in the next field, 0.to 8 bytes. 

67-74 Password. A password is often used to verify access to a system under a 
particular user identification. In RSTS/E, this password is analogous to 
the password used in conjunction with the project-programmer number 
used at log-in. A password supplied here must be acceptable to the 
remote system or program, if one is required. If not required. the length 
(byte 66) should be set to zero. 


75 Reserved — must be zero. 
76 Length of the accounting information specified in the following field. 0 to 
16 bytes. 


77-92 Accounting information. Many systems require a billing account number 
in addition to user identification and password. The accounting field is 
provided for this purpose. Once again, such information need only be 
specified here if it is required by the remote system or program. If it is 
not required, the length (byte 76) should be set to zero. 


Reserved for future use. Currently ignored by DECnet/E but should be passed 
as zeros. 


Possible Errors: 


errval 


14 


18 


Error Text and Meaning 


BAD DIRECTORY ON DEVICE 


Network operations have been terminated due to an internal error. Notify the 
system manager. ; 


ACCOUNT OR DEVICE IN USE 


The calling program already has a logical link with the same user link address 
(ula) as specified in this Connect Initiate Message. A different ula must be used or 
the existing link must be disconnected. 


NOT A VALID DEVICE 
The node named in the Connect Data Block is not known to the svstem. 


DEVICE HUNG OR WRITE LOCKED 


The node named in the Connect Data Block is known to the system but is cur- 
rently inactive. There is no physical communication path to the node. 


TOO MANY OPEN FILES ON UNIT 


The total number of logical links allowed for the local node has been reached. A 
later try may succeed. (The system manager can set a limit on the total number of ~ 
links. If this limit is inadequate, see the system manager.) 


ILLEGAL SYS() USAGE 
One of several possibilities: 


1. The calling program is not a declared receiver. A Declare Receiver cal] must 
be issued before this call is given. 


9. The Declare Receiver call for the calling program had a null logical name and 
a zero object type code. There is no way to identify the program to the remote 
system. Issue a Remove Receiver call and reissue the Declare Receiver call. 


(continued on next page) 


Network Programming in FORTRAN 


errval Error Text and Meaning 


3. An invalid value was detected in one of the following fields: 
e Remote program field in the Connect Data Block. 
© One of the three access control fields in the Connect Data Block. 


e The user link address (ula) given was zero. Valid values range from 1 to 
255. 


© The local link modifier (//mod) value must be 0, 1, or 2. 


e The remote descriptor length (byte 10 in the Connect Data Block) was 
nonzero but the descriptor field was null (all zeros). 


22 DISK PACK IS LOCKED OUT 


NSP cannot create a new logical link because the physical line to the remote node 
_ or the local node itself has been scheduled for shutdown by the system manager. 


31 ILLEGAL BYTE COUNT FOR I/O 


The length field passed in buflen is invalid. The length of the buffer must be 
between 120 bytes and 136 bytes for a Connect Initiate Message. 


32 NO BUFFER SPACE AVAILABLE 
System buffers are not currently available to store this message. A later try may 
succeed. 

62 NO RUN-TIME SYSTEM 


NSP has not been enabled. Normal DECnet calls cannot be executed until the 
system manager enables NSP. 


66 MISSING SPECIAL FEATURE 


DECnet was‘ not installed at system generation time. The network functions 
cannot be executed. 


Example: 


The following example shows a Connect Initiate Message directed to a pro- 
gram declared as a receiver with object type code 254 at node MIAMI. The 
Connect Data Block uses a format 2 name to address the remote program. 
Note that the replacement statement OBJTYP = 254 sets the correct byte in 
the Connect Data Block to 254, even though LOGICAL*1 values in FOR- 
TRAN are treated as signed values. NSP supplies the local program identifi- 
cation. No access control fields are used so the rest of the Connect Data Block 
is filled with zeros. A user link address of 27 is established and the receive 
maximum is set to 512. LLMOD is set to indicate that the local program 
requests message flow control. The message data “OPTION2” is sent fol- 
lowing the Connect Data Block. 
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LOGICAL#1 COB(13G) »MSG(1G) »NODE(6) »,OBJTYP »FMT »LGT 
INTEGER BUFLEN + BUFOFF »ULA»LLMOD »RMAX FERRVAL 
EQUIVALENCE (COB(1) »NODE(1)) »(COB(7) »FMT) »(COB(8) ,OBITYP)) 
EQUIVALENCE ((COB(121) »MSG(1)) 
DO 20 I = 1+136 
20 COB(I) = 9 


ULA = 27 

LLMOD = 2 

RMAX = 512 

FMT = 2 

OBJTYP = 254 

BUFLEN = 127 

BUFOFF = 0 

CALL NTCI(ERRVAL »ULA »LLMOD +RMAX +COB +BUFLEN BUF OFF ) 


DATA NOOE/"M" had "At ,"M" oy" "7 
DATA MSG/"Q" "pt "T" "I" »"Q" o"N"” os 
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5.6.3 Send Connect Confirm Message (NTCC) | (DECnet) 


The NTCC call is used to accept a remote program’s request for a logical link. 
The call establishes the user link address that the calling program will use to 
refer to the link. The local link address assigned by the local NSP identifies 
the particular link being accepted. The desired flow control option and the 
receive maximum for the link are also specified. Up to 16 bytes of message 
data can be passed to the remote program. 


FORTRAN Call Format: 
CALL NTCC(errval,ula,lla,llmod,rmax, buffer, buflen, bufoff) 


Argument Descriptions: 


errval 


The errval argument must be an integer variable name. This variable is set to 
zero if the NTCC call succeeds. If an error occurs, errval is set to one of the 
error codes listed under ‘Possible Errors” at the end of this section. 


ula 


The user link address (u/a) is an integer value in the range of 1 to 255. Later 
calls to send and receive messages use this value to refer to the logical link. 


The ula must be unique within the program at any given time. That is, one 
program cannot have two different logical links with the same ula at the same 


time. 


ila 


The local link address (lla) is an integer value that identifies the link being 
accepted. It is a number assigned by the local NSP when it received the 
Connect Initiate Message requesting the link. The local link address is passed 
to the local program in bytes 5-6 of the received Connect Initiate Message. 
(Section 5.7.2 describes the information returned for a received Connect Ini- 
tiate Message.) 


llmod 


The integer value /l/mod indicates the type of flow control requested for this 
end of the logical link. Acceptable values and meanings are: 


0 No flow control 
1 Segment flow control 
2 Message flow control 


Flow control is described in detail in Chapter 4. Remember that both pro- - 
grams in a logical link select their own flow control independent of each other. 
The llmod value is the selection made by the calling program. If llmod is 
nonzero, the calling program must issue Link Service (NTLS) calls to request 
Network Data Messages from the other program. 
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A program that has limited buffer space and is not designed to process large 
messages in small pieces can impose a limit on the amount of user message 
data it is willing to receive on a logical link. The integer value rmax specifies 
this limit in bytes. 


The size of the receive buffers allocated by NSP will itself limit the amount of 
data that can be passed in a single Network Data Message. If the maximum 
size set for NSP by Network Management is not large enough to handle the 
receive maximum as specified in rmazx, the local NSP will alter the maximum 
to the smaller limit before forwarding the Connect Confirm Message to the 
remote node. If rmax = 0, NSP supplies the size of its receive buffers as a 
default value. 


The remote NSP uses this value to establish a transmit maximum for its end 
of the logical link. If the remote system is also a RSTS/E system, this transmit 
maximum is passed on to the remote program. The remote program must 
limit the amount of user message data it sends over the logical link according 
to this value. 


See the discussion of the buflen argument for the Receive call (MRCV) in 
Section 5.7 for a description of how to process large messages in small pieces. 


buffer 


This argument defines the starting address of a buffer containing optional 
user message data. The data in the buffer is assumed to be in contiguous 
bytes. If a nonzero offset is given (see bufoff), the offset is added to the 
starting address of the buffer. 


buflen 
This integer value defines the number of bytes of user data to be sent: 0 to 16. 
bufoff 


This integer value defines an offset, in bytes, from the address specified by the 
buffer argument. The offset value is added to the starting address of the buffer 
to define where the user data begins. For example, if bufoff = 20, the user data 
begins in byte 21 of the buffer. 


byte 1 20) 21 (buflen+20) 
oe 
whole buffer 
NOTE 


The FORTRAN interface makes no checks for inconsistencies 
in the buffer, buflen, and bufoff values specified. A program 

_ could, for example, specify a buflen of 16 and a bufoff of -100. 
Sixteen bytes beginning at buffer-100 would be sent. 
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Possible Errors: 


errval 


10 


18 


31 


32 


62 


Error Text and Meaning 


BAD DIRECTORY ON DEVICE 


Network operations have been terminated due ‘to an internal error. Notify the 
system manager. 


ACCOUNT OR DEVICE IN USE 


A logical link is currently active for the calling program with the same user link 
address (ula) as specified in this Connect Confirm Message. A different ula must 
be used or the existing link must be disconnected. 


CAN’T FIND FILE OR ACCOUNT © 


The local link address (lla) does not correspond to any known logical link for the 
calling program. Either the /la is incorrect or the originating request has been 
cancelled. In the latter case, a Link Abort Message has already been queued for 
this link. The lla field in the received Link Abort Message identifies the link since 
no ula was ever established. 


PROTECTION VIOLATION 


Some procedural error has occurred. Sending a Connect Confirm Message for a 
link that is not waiting for confirmation will cause this error. For example, a 
second Connect Confirm Message for the same logical link will cause this error 
because the link is already established. 


ILLEGAL SYS() USAGE 
One of two possibilities: 


1. The calling program is not a declared receiver. A Declare Receiver call must 
be issued before this call is given. 


2. An invalid value was detected in one of the following fields: 


1. The user link address (ula) given was zero. Valid values range from 1 to 
255. 


2. The local link modifier (//mod) value must be 0, 1, or 2. 
ILLEGAL BYTE COUNT FOR I/O 


The length field passed in bu/len is invalid. It must be between 0 and ‘16 bytes for 
a Connect Confirm Message. 


NO BUFFER SPACE AVAILABLE 


System buffers are not currently available to store this message. A later try may 
succeed. 


NO RUN-TIME SYSTEM 


NSP has not been enabled. Normal DECnet calls cannot be executed until the 
system manager enables NSP. 


MISSING SPECIAL FEATURE 


DECnet was not installed at system generation time. The network functions 
cannot be executed. 
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Example: 


In the following example, an NTCC call responds to a received Connect Ini- 
tiate Message that was stored in the byte array RETBUF. The local link 
address is stored in bytes 5 and 6 of this string and the EQUIVALENCE sets 
the integer variable LLA to access these bytes. The call also establishes a user 
link address of 15, a receive maximum of 256 bytes, and indicates that the 
program requests message flow control. No user message data is sent, so a 
dummy argument is given for the starting address with zero values for the 
length and offset. 


LOGICAL#1 RETBUF(4O) 
INTEGER ERRVAL »ULA »LLMOD +RMAX +LLA 
EQUIVALENCE (RETBUF(S) »LLA) 


° 


ULA = 15 

LLMOO = 2 

RMAX = 256 

CALL NTCC(ERRVAL »ULA »LLA »LLMOD »RMAX »NOBUF 19 +0) 
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5.6.4 Send Connect Reject Message (NTCR) (DECnet) 


The NTCR call is used to reject a remote program’s request for a logical link. 
The link is identified by the local link address established by the local NSP. 
Up to 16 bytes of user message data can be sent to the remote program as part 
of the Connect Reject Message. 


FORTRAN Call Format: 
CALL NTCR(errval,lla,reason, buffer, buflen, bufoff) 


Argument Descriptions: 
errval 


The errval argument must be an integer variable name. If the NTCR call 
succeeds, this variable is set to zero. If an error occurs, errval is set to one of 
the error codes listed under “Possible Errors” at the end of this section. 


tla 


The local link address (lla) is an integer value that identifies the link being 
rejected. It is a number assigned by the local NSP when it received the 
Connect Initiate Message requesting the link. The local link address is passed 
to the local program in bytes 5-6 of a received Connect Initiate Message. 
(Section 5.7.2 describes the information returned for a received Connect Ini- 
tiate Message.) 


reason 


DECnet/E NSP allows a program to specify one of the following three reason 
code values for this word: 0, 34, or 36. 


Most user programs will simply use 0. If any reason is supplied for rejecting 
the connection, it is passed in the 16-byte user data area. 


The values 34 and 36 are allowed so that DECnet/E support programs (such 
as FAL and NFT) can reject unauthorized or improper requests for access to 
local RSTS/E files in a manner agreed upon as part of the overall DECnet 
design. There is no reason for a user program to use the 34 and 36 codes unless 
- it talks to other programs that interpret them. All DECnet programs that are 
concerned with protection against unauthorized access are designed to recog- 
nize these codes. These programs take appropriate action (such as displaying 
an error message to a user) when they receive such a connect rejection. 


The value 34 indicates that the user ID and password subfields in the Connect 
Data Block of the remote program’s Connect Initiate Message do not corre- 
spond to any valid user known to the local system. 


The value 36 indicates that, while the user ID and password subfields are 
acceptable, the account subfield is not. For example, the specified user may 
not be authorized to use that billing account or the account may be ex- 
hausted. 
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buffer 


This argument defines the starting address of a buffer containing the optional 
user message data. The data in the buffer is assumed to be in contiguous 
bytes. (See Section 5.1.1 for a discussion of how to set up buffers for message 
operations.) If a nonzero offset is given (see bufoff), the offset is added to the 
starting address of the buffer. 


buflen 


This integer value defines the number of bytes of user data to be sent: 0 to 16. 


bufoft 


This integer value defines an offset, in bytes, from the beginning of the buffer 
specified by the buffer argument. The value of bufoff is added to the buffer 
address to define the beginning address of the user message data. For ex- 
ample, if bufoff = 20, the user data begins in byte 21 of the buffer. 





20] 21 (buflen+20) 


whole buffer 


byte 1 


NOTE 


The FORTRAN interface makes no checks for inconsistencies 
in the buffer, buflen, and bufoff values specified. A program 
could, for example, specify a buflen of 16 and a bufoff of -100. 
Sixteen bytes beginning at bu/fer-100 would be sent. 


Possible Errors: 


errval Error Text and Meaning 


1 BAD DIRECTORY ON DEVICE 


Network operations have been terminated due to an internal error. Notify the 
system manager. 


5 CAN’T FIND FILE OR ACCOUNT 


The local link address (lla) does not correspond to any known logical link for the 
calling program. Either the lla is incorrect or the originating connect request has 
been cancelled. In the latter case, a Link Abort Message has already been queued 
for this link. The lla field in the received Link Abort Message identifies the link 
since no ula was ever established. 


10 PROTECTION VIOLATION 


Some procedural error has occurred. Sending a Connect Reject Message for a link 
that is not waiting for confirmation will cause this error. For example, sending a 
Connect Reject Message for a link that is already established will return this 


error. 
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errval 


18 


31 


32 


62 


Example: 


Error Text and Meaning 


ILLEGAL SYS() USAGE 
One of two possibilities: 


1. The calling program is not a declared receiver. A Declare Receiver call must 
be issued before this call is given. 


2. The reason code supplied with the Connect Reject Message was not 0, 34, or 
36. 


ILLEGAL BYTE COUNT FOR I/O 


The length field passed in buflen is invalid. The length of the buffer must be 
between 0 and 16 bytes for a Connect Reject Message. 


NO BUFFER SPACE AVAILABLE 


System buffers are not currently available to store this message. A later try may 
succeed. 


NO RUN-TIME SYSTEM 


NSP kas not been enabled. Normal DECnet calls cannot be executed until the 
system manager enables NSP. 


MISSING SPECIAL FEATURE 


DECnet was not installed at system generation time. The network functions 
cannot be executed. 


In the following example, a NTCR call responds to a received Connect Initiate 
Message stored in the receiving byte array RETBUF. A reason code of 0 is 
supplied. The local program notifies the remote program of the reason for 
rejection with user data. - 


LOGICAL#1 RETBUF‘40) 
INTEGER ERRVAL »LLA REASON -BUFLEN +BUFOFF 
EQUIVALENCE (RETBUF(S) »LLA) ‘ 


BUFLEN = 8 
BUFOFF = 0 
REASON = 0 
CALL NTCR(ERRVAL »LLA »REASON » "TOO LATE" »BUFLEN »BUFOFF ) 
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5.6.5 Send Network Data Message (NTDM) (DECnet) 


The NTDM call transmits user data — a segment as defined in Chapter 4 — 
over an established logical link. A flag word indicates whether or not the 
segment is the end of a logical message. If the remote program requested 
segment or message flow control when the link was established, requests for 
data must be outstanding or this call will result in an error. 


FORTRAN Cail Format: 

CALL NTDM(errval,retbuf,ula,dmflgs, buffer, buflen, bufoff) 
Argument Descriptions: 

errval 


The errval argument must be an integer variable name. This variable is set to 
zero if the NTDM call succeeds. If an error occurs, errval is set to one of the 
error codes listed under “Possible Errors” at the end of this section. 


retbuf 


This argument names the starting address of the buffer to receive link status 
information returned by the call. This argument must be specified regardless 
of whether or not link status information is requested and should refer to a 
preallocated buffer at least 40 bytes long. 


ula 


The ula is an integer value specifying the user link address (1 to 255) chosen 
by the calling program in its Connect Initiate (NTCI) or Connect Confirm 
(NTCC) Message sent during the connection sequence. 


dmfigs - 


The dmflgs argument is an integer value that can be coded as the sum of three 
bit values: 


dmflgs = rls + eom + bom 


The low-order two bits of the dmflgs argument (eom + bom) indicate whether 
the segment being sent in this Network Data Message is the first, last, middle, 
or sole segment of a logical message. If message flow control was requested by 
the remote program when the link was established, NSP uses these.two bits to 
regulate the transmission of logical messages as the remote program requests 
them. (See Chapter 4 for a full discussion of flow control.) 


eom bom 

0 0 Middle segment of a logical message 
0 1 First segment of a logical message 

2 0 Last segment of a logical message 

2 1 Sole segment of a logical message 


DECnet/E NSP uses the eom bit to count logical messages transmitted to the 
remote program. The bom bit is not used in maintaining the logical message 
request count but is simply passed to the remote system and program. 
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NSP also uses the eom bit to determine whether it will permit a disconnect of 
the logical link. If a disconnect is requested but the last Network Data Mes- 
sage sent did not have the eom bit set, NSP assumes that the last message has 
not been completely sent and will not permit the disconnect. This is always 
done, irrespective of the flow control option selected by the receiver. 


Some DECnet implementations require that the eom flag be set to terminate 
an asynchronous I/O operation. It is suggested that when segment flow control 
or.no flow control was requested by the remote program, the eom flag always 
be set. 


The ris bit is used to request that link status information. be returned to the 
retbuf buffer when this call has completed successfully. 


rls = 128 Link status information is returned. 
rls= 0O No link status information is returned. 


If link status information is requested, it is returned in the same format as a 
received Link Service Message (Section 5.7.7). If no link status information is 
requested, random data is returned. 


buffer 


This argument defines the starting address of a buffer containing the user 
message data. If a nonzero offset is given (see bufoff), the offset is added to the 
starting address of the buffer. : 


buflen 


This integer value defines the number of bytes to be sent. The maximum 
amount of data that can be transferred over the logical link is established by 
the remote program or the remote NSP. It is passed on to the calling program 
as a transmit maximum (the tmax value in a received Connect Initiate or 
Connect Confirm Message, Sections 5.7.2 and 5.7.3). Thus, the value of buflen 
can range from 1 through tmax. 


bufoff 


This integer value defines an offset, in bytes, from the starting address of the 
buffer defined by the buffer argument. The value of bufoff is added to the 
buffer address to define the beginning address of the user message data. For 
example, if bufoff = 20, the user data begins in byte 21 of the buffer. 


byte 1 20| 21 (buflen+20) 


whole buffer 


NOTE 


The FORTRAN interface makes no checks for inconsistencies 
in the buffer, buflen, and bufoff values specified. A program 
could, for example, specify a buflen of 100 and a bufoff of 20. 
One hundred bytes beginning at buffer+20 would be sent. 
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Possible Errors: 


errval 


10 


31 


32 


Error Text and Meaning 


BAD DIRECTORY ON DEVICE 


Network operations have been terminated due to an internal error. Notify the 
system manager. 


NO ROOM FOR USER ON DEVICE 


The Data Message transmit queue for this logical link is full. NSP is waiting for 
acknowledgment from the remote system for previously sent Network Data Mes- 
sages. No more can be sent until at least one of the outstanding messages in the 
transmit queue is acknowledged. This condition is temporary and no Link Service 
Message notification occurs when the condition clears. The program should 
simply retry the send after a short (1 to 5 second) delay. (See Chapter 4 for a full 
discussion of flow control.) - 


CAN’T FIND FILE OR ACCOUNT 


The user link address (ula) specified in the call does not correspond to any known 
logical link for the calling program. Either the ula is incorrect or the logical link 
has been disconnected. In the latter case, a Disconnect or Link Abort Message has 
already been queued for this link. 


PROTECTION VIOLATION 


Some procedural error has occurred. Sending a Network Data Message over a 
logical link that has not yet been confirmed will cause this error. 


ILLEGAL SYS() USAGE 
One of two possibilities: 


1. The calling program is not a declared receiver. A Declare Receiver call must 
be issued before this call is given. 


2. The ula specified is zero. It must be in the range of 1 to 255. 
DISK BLOCK IS INTERLOCKED 


Either the remote system has inhibited transmission on this link because ot a 
backpressure condition or there are no outstanding requests for segments or log- 
ical messages from the remote program (assuming it requested segment or mes- 
sage flow control for the link). 


The calling program will be notified with a Link Service Message when the condi- 
tion clears, as described in Chapter 4. 


ILLEGAL BYTE COUNT FOR I/O 


The length field passed in buflen is invalid. The length of the buffer must be 
between 1 and the transmit maximum (tmax) established by the remote program 
or system in its Connect Initiate or Connect Confirm Message for this logical link. 


NO BUFFER SPACE AVAILABLE 


System buffers are not currently available to store this message. A later try may 
succeed. 


(continued on next page) 
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errval Error Text and Meaning 


62 NO RUN-TIME SYSTEM 


NSP has not been enabled. Normal DECnet calls cannot be executed until the 
system manager enables NSP. 


66 MISSING SPECIAL FEATURE 


DECnet was not installed at system generation time. The network functions 
cannot be executed. 


Example: 


The following example sends a Network Data Message over a logical link. The 
user link address is 20. The value for DMFLGS identifies the message data as 
the sole segment of a logical message and requests the return of link status 
information. The buffer for returned data is set up as a 40-byte LOGICAL*1 
array. Then, after the NTDM call, the returned data is placed as positive 
integer values in array IR2. 


The call sends 400 bytes of data from array A (each real value is 4 bytes long). 
After the call, the program checks for an error. If none occurred, the program 
then determines if there are any pending messages. If so, the program 
branches to receive and process messages. If not, the program simply con- 
tinues. 


LOGICAL#1 RETBUF (40), R2(40) 
INTEGER EOM + BOM» RLS +DMFLGS rERRVAL +ULA + IR2( 40) YMCNT »MMAX 
REAL A(10+10) 
EQUIVALENCE (IRZ(1) R201 91)) oCMONT p IR2(32)) o (MMAK FTR2(31)) 
DO 100 121,40 
100 R2(2+1I) = 0 
EOM = 2 
BOM = 1 
RLS = 128 
ULA = 20 
OMFLGS = EOM + BOM + RLS 
CALL NTOM(ERRVAL »RETBUF +ULA +DMFLGS 1A 1400 0) 
IF ERRVAL .NE. 0 GOTO 4000 
DO 260 I = 140 


260 R2(1eI) = R(T) 
IF MCNT «NE. 90 GOTO 3000 
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5.6.6 Send Interrupt Message (NTIN) (DECnet) 


The NTIN call transmits an Interrupt Message to a remote program over an 
established logical link. All DECnet systems are designed to deliver Interrupt 
Messages ahead of other messages. If the remote system is a DECnet/E 
system, the Interrupt Message will be placed at the head of the pending 
message queue, behind the first message (since it may already be partly 
received) and behind any other pending Interrupt Messages queued for the 
program. Interrupt Messages are subject to flow control, as described in 
Chapter 4. 


FORTRAN Call Format: 

CALL NTIN(errval,retbuf.ula,inflgs, buffer, buflen, bufoff) 
Argument Descriptions: 

errval 


The errval argument must be an integer variable name. This variable is set to 
zero if the NTIN call succeeds. If an error occurs, errval is set to one of the 
error codes listed under ‘Possible Errors” at the end of this section. 


retbuf 


This argument names the starting address of the buffer to receive link status 
information returned by the call. It must be specified regardless of whether or 
not link status information is requested and should refer to a preallocated 
buffer at least 40 bytes long. 


ula 


The ula is an integer value giving the user link address (1 to 255) chosen by 
the calling program in its Connect Initiate (NTCI) or Connect Contirm 
(NTCC) Message sent during the connection sequence. 


inflgs 


The inflgs argument is an integer value. It indicates whether link status 
information is to be returned to retbuf when the call completes successfully. 
This field should be coded as follows: 

inflgs = rls 
where 


rls = 128 Link status information is returned. 
rls = 0 No link status information is returned. 


If link status information is requested, it is returned in the same format as a 
received Link Service Message (Section 5.7.7). If no link status information is 
requested, random data is returned. 
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buffer 


This argument defines the starting address of a buffer containing optional 
user message data. If a nonzero offset is given (see bufoff), the offset is added 
to the starting address of the buffer to determine where the data begins. 


buflen 


This integer value defines the number of bytes of user data to be sent: 0 to 16. 


bufoff 


This integer value defines an offset, in bytes, from the beginning of the buffer 
specified by the buffer argument. The value of bufoff is added to the starting 
address of the buffer to define the beginning address of the user message data. 
For example, if bufoff = 20, the user data begins in byte 21 of the buffer. 


byte 1 20} 21 (buflen+20) 


whole buffer 


NOTE 


The FORTRAN interface makes no checks for inconsistencies 
in the buffer, buflen, and bufoff values specified. A program 
could, for example, specify a buflen of 16 and a bufoff of -100. 
Sixteen bytes beginning at buffer-100 would be sent. 


Possible Errors: 


errval Error Text and Meaning 


1 BAD DIRECTORY ON DEVICE 


Network operations have been terminated due to an internal error. Notify the 
system manager. - 


4 NO ROOM FOR USER ON DEVICE 


The Interrupt/Link Service transmit queue for this logical link is full. NSP is 
waiting for acknowledgment from the remote system for previously sent Interrupt 
or Link Service Messages. No Interrupt or Link Service Messages can be sent 
until at least one of the outstanding messages in the transmit queue is acknowl- 
edged. This condition is temporary and no Link Service Message notification 
occurs when the condition clears. The program should simply retry the send 
request after a short delay of one to five seconds. (See Chapter 4 for a full discus- 
. sion of flow control.) 


(continued on next page) 
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errval 


10 


18. 


19 


31 


32 


62 


Example: 


Error Text and Meaning 
CAN'T FIND FILE OR ACCOUNT 


The local link address (/la) does not correspond to any known logical link for the 
calling program. Either the lla is incorrect or the originating connect request has 
been cancelled. In the latter case, a Disconnect or Link Abort Message has already 
been queued for this link. 


PROTECTION VIOLATION 


Some procedural error has occurred. Sending an Interrupt Message over a logical 
link that has not yet been confirmed will cause this error. 


ILLEGAL SYS() USAGE 
One of two possibilities: 


1. The calling program is not a declared receiver. A Declare Receiver call must 
be issued before this call is given. 


2. The user link address (ula) given was zero. Valid values range from | to 255. 
DISK BLOCK IS INTERLOCKED 


The remote NSP has prohibited transmission of Interrupt Messages over this 
logical link according to its rules for Interrupt Message flow control. A Link 
Service Message will be delivered to the calling program when the condition 
clears. (See Chapter 4 for a full discussion of flow control.) 


ILLEGAL BYTE COUNT FOR I/O 


The length field passed in buflen is invalid. The length of the buffer must be 
between 0 and 16 bytes for an Interrupt Message. 


NO BUFFER SPACE AVAILABLE 


System buffers are not currently available to store this message. A later try may 
succeed. 


NO RUN-TIME SYSTEM 


NSP has not been enabled. Normal DECnet calls cannot be executed until the 
system manager enables NSP. 


‘MISSING SPECIAL FEATURE 


DECnet was not installed at system generation time. The network functions 
cannot be executed. 


The following example shows a NTIN call for logical link 15. The call sends 

the message data “TIMEOUT” and requests no link status information. A 

dummy buffer must be defined and referenced, however, so LOGICAL*1 
_ array named DUMMY is defined and used in the call. 


LOGICAL*1 
INTEGER 


INFLGS = 
ULA = 15 


DUMMY (40) 
ERRVAL »INFLGS +ULA . 


QO 


CALL NTIN(ERRVAL /OUMMY »-ULA,INFLGS + "TIMEOUT" +750) 
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5.6.7 Send Link Service Message (NTLS) (DECnet) 


The NTLS call can be used to: (1) request data from a remote program over a 
flow-controlled logical link (Chapter 4), (2) reenable incoming Interrupt Mes- 
sages over a logical link (Chapter 4), or (3) obtain status information for the 
link. No user data is allowed with a Link Service Message. 


FORTRAN Call Format: 
CALL NTLS(errval,retbuf,ula,lsflgs,drent,ircnt) 


Argument Descriptions: 


errval 


The errval argument must be an integer variable name. This variable is set to 
zero if the NTLS call succeeds. If an error occurs, errval is set to one of the 
error codes listed under ‘‘Possible Errors” at the end of this section. 


retbuf 


This argument names the starting address of the buffer to receive link status 
information returned by the call. It must be specified regardless of whether or 
not link status information is requested and should refer to a preallocated 
buffer at least 40 bytes long. 


ula 


The ula is an integer value identifying the user link address (1 to 255) chosen 
by the calling program in its Connect Initiate (NTCI) or Connect Confirm 
(NTCC) Message sent during the connection sequence. 


Isflgs 


The link service flags argument is an integer value coded as the sum of two 
values: Isflgs = ris + opr. The low-order two bits (opr) indicate the purpose of 
the call. 


opr = 0 Indicates the call is requesting segments or logical messages 
from the remote program. In this case, the drent argument is 
interpreted as the number of segments or logical messages being 
requested. This form of the call can be used only when the 
calling program requested message or segment flow control in its 
Connect Initiate or Connect Confirm Message for this logical 
link. If no flow control was requested, an NTLS call with opr = 0 
will fail with errval = 18. © 


= 1 Indicates the call is to reenable incoming Interrupt Messages for 
this link. In this case, the irent argument is interpreted as the 
number of Interrupt Messages requested (always 1). 


= 2 Indicates the call is to obtain status information only. In this 
case, the drcnt and ircnt arguments are ignored. 
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The rls bit can be used when opr = 0 or 1 to request that link status informa- 
tion be returned to the return buffer (defined by retbuf) when the call com- 
pletes successfully. 


rls = 128 Link status information is returned. 
rlis= 0 No link status information is returned. 


Link status information is always returned when opr = 2. If the information is 
requested, it is returned in the same format as a received Link Service Mes- 
sage (Section 5.7.7). If no link status information is requested, random data is 
returned. 


drent 


The data request count (drent) is meaningful only when opr = 0 and indicates 
the maximum number of segments or logical messages being requested from 
the remote program. Depending on the flow control option in effect for the 
logical link, the value is interpretted as either a segment counter (for segment 
flow control) or a logical message counter (for message flow control). In either 
case it is an incremental count, added to the counter of outstanding requests 
for segments or logical messages kept by the remote and local NSP (see 
Chapter 4). An error is returned if the drent specified increases the counter to 
more than 127. 


irent 


The interrupt request count (ircnt) is meaningful only when opr = 1 and 
indicates the number of Interrupt Messages being requested. DECnet/E al- 
lows only one interrupt request outstanding for a logical link at any given 
time. Hence, the integer value ircnt must always be 1 when opr = 1 and has 
the effect of reenabling Interrupt Messages on the logical link. Remember that 
Interrupt Messages can be reenabled only when the previous Interrupt Mes- 
sage for this logical link, if any, has been received from the pending message 
queue. If it has not, the call will fail with an error (errva/ = 19). 


Possible Errors: 


errval Error Text and Meaning 


1 BAD DIRECTORY ON DEVICE 


Network operations have been terminated due to an internal error. Notify the 
system manager. 


4 NO ROOM FOR USER ON DEVICE 


The Interrupt/Link Service transmit queue for this logical link is full. NSP is 
waiting for acknowledgment from the remote system for previously sent Interrupt 
or Link Service Messages. No Interrupt or Link Service Messages can be sent 
until at least one of the outstanding messages in the transmit queue is acknowl- 
edged. This condition is temporary and will not cause a Link Service Message to 
be queued when the condition clears. The program should simply retry the send 
request after a short delay of one to five seconds. (See Chapter 4 for a full discus- 
sion of flow control.) 


(continued on next page) 
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Error Text and Meaning 


CAN’T FIND FILE OR ACCOUNT 


The user link address (ula) specified in the call does not correspond to any known 
logical link for the calling program. Either the ula is incorrect or the logical link 
has been disconnected. In the latter case, a Disconnect or Link Abort Message has 
already been queued for this link. 


PROTECTION VIOLATION 


Some procedural error has occurred. Sending a Link Service Message over a 
logical link that has not yet been confirmed will cause this error. 


ILLEGAL SYS() USAGE 
One of several possibilities: 


1. The calling program is not a declared receiver. A Declare Receiver call must 
be issued before this call is given. 


2. The opr value is not 0, 1, or 2. 


3. The opr value is 0, but the program did not request flow control for the logical 
link in its Connect Initiate (NTCI) or Connect Confirm (NTCC) Message. 


4. The data request count (drent) increased the count of outstanding segments or 
logical messages requested to more than 127. 


¢ 
5. The opr value is 1, indicating a request for an Interrupt Message, but the ircnt 
argument does not equal 1. 


6. The opr value is 1, indicating a request for an Interrupt Message, but the 
outstanding request counter for Interrupt Messages already equals 1. 


7. The ula specified is zero. It must be within the range 1 to 255. 
DISK BLOCK IS INTERLOCKED 


The opr value is 1, indicating a request for an Interrupt Message, but there is 
already an Interrupt Message queued for this logical link. (See Chapter 4 for 
details on flow control.) 


NO BUFFER SPACE AVAILABLE 


System buffers are not currently available to store this message. A later try may 
succeed. 


NO RUN-TIME SYSTEM 


NSP has not been enabled. Normal DECnet calls cannot be executed until the 
system manager enables NSP. 


MISSING SPECIAL FEATURE 


DECnet was not installed at system generation time. The network functions 
cannot be executed. : 
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Example: 


The following example of the NTLS call requests five segments from the 
remote program over logical link 23. (Assume that the program requested 
segment flow control in its NTCI or NTCC call for this link). 


INTEGER OPR+RLS +ERRVAL »ULA»LSFLGS »DRCNT 
LOGICAL#1 A(40) 

OPR = 9 
RLS = 128 
ULA = 23 
LSFLGS = RLS + OPR 

DRCNT = 5 

CALL NTLS(ERRVAL +A» ULA +L SFLGS rDRENT +0) 
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5.6.8 Send Disconnect Message (NTDI) (DECnet) 


The NTDI call is used to terminate an established logical link. Messages in 
the pending message queue will remain but no more messages can be sent over 
the link. The user link address is freed and can be used for another logical 
link. If the last Network Data Message sent did not have the end of message 
flag set, or if any Network Data, Interrupt, or Link Service Messages are still 
waiting for acknowledgment in the transmit queues for this logical link, this 
call will fail with an error. 


Successful completion of an NTDI call assures the calling program that the 
remote system has received and acknowledged all Network Data, Interrupt, 
and Link Service Messages previously sent over the link. It does not, however, 
guarantee that the receiving program has processed the messages. The 
Disconnect Message is useful in “master-slave” communication where the 
master program only transmits data and the slave program only receives data 
(see Section 3.13). Otherwise, the NTDI call provides no particular advantage 
over an NTLA call (see Section 5.6.9) in terminating a logical link. 


Up to 16 bytes cf user data can be sent with the Disconnect Message. 
FORTRAN Cail Format: 

CALL NTDI\(errval,ula, buffer, buflen, bufoff) 

Argument Descriptions: 

errval 


The errval argument must be an integer variable name. This variable is set to 
zero if the NTDI call succeeds. If an error occurs, errval is set to one of the 
error codes listed under ‘Possible Errors’ at the end of this section. 


ula 


The ula is an integer value identifying the user link address (1 to 255) chosen 
by the calling program in its Connect Initiate (NTCI) or Connect Confirm 
(NTCC) Message sent during the connection sequence. 


buffer 


This argument defines the starting address of a buffer containing the optional 
user message data. If a nonzero offset is given (see bufoff), the offset is added 
to the starting address of the buffer. 


buflen 


This integer argument defines the number of bytes of user data to be sent: 0 to 
16. , 


bufoff 


This integer value defines an offset, in bytes, from the beginning of the buffer 
specified by the buffer argument. The value of bufo/f is added to the starting 
address of the buffer to define the beginning address of the user message data. 
For example, if bufoff = 20, the user data begins in byte 21 of the buffer. 
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20| 21 


whole buffer 
NOTE 


byte 1 (buflen +20) 


The FORTRAN interface makes no checks for inconsistencies 
in the buffer, buflen, and bufoff values specified. A program 
could, for example, specify a buffer 20 bytes long, an offset of 
10, and a buflen of 16. In that case, 16 bytes would be sent: the 
last 10 bytes of the buffer and 6 bytes of whatever is beyond the 
buffer in memory. 


Possible Errors: 


errval Error Text and Meaning 


1 BAD DIRECTORY ON DEVICE 


Network operations have been terminated due to an internal error. Notify the 
system manager. 


4 NO ROOM FOR USER ON DEVICE 


There are outstanding unacknowledged messages on either the Data Message 
transmit queue or the Interrupt/Link Service transmit queue. All messages previ- 
ously sent over the logical link must be acknowledged before the Disconnect 
Message can be sent. (If an immediate unconditional termination of the logical 
link is desired, use the NTLA call.) 


5 CAN’T FIND FILE OR ACCOUNT 


The user link address (ula) specified in the call does not correspond to any known 
logical link for the calling program. Either the ula is incorrect or the logical link 
has been disconnected. In the latter case. a Disconnect or Link Abort Message has 
already been queued for this link. 


10 PROTECTION VIOLATION 


Some procedural error has occurred. Sending a Disconnect Message over a logical 
link that has not yet been confirmed will cause this error. 


18 ILLEGAL SYS() USAGE 
One of two possibilities: 


1. The calling program is not a declared receiver. A Declare Receiver call must 
be issued before this call is given. 


2. The ula specified is zero. It must be within the range 1 to 255. 
19 DISK BLOCK IS INTERLOCKED 


The last segment sent by the local program over this logical link did not have the 
eom flag set. NSP will not permit a logical link to be disconnected unless all 
messages have been completely sent. (Note that this test of the eom flag is done 
irregardless of the flow control option chosen by the local program.) 


(continued on next page) 


Network Programming in FORTRAN 


errval _- Error Text and Meaning 


31 


32 


62 


Example: 


ILLEGAL BYTE COUNT FOR I/O 


The length field passed in buflen is invalid. The length of the buffer must be 
between 0 and 16 for a Disconnect Message. 


NO BUFFER SPACE AVAILABLE 


System buffers are not currently available to store this message. A later try may 
succeed. 


NO RUN-TIME SYSTEM 


NSP has not been enabled. Normal DECnet calls cannot be executed until the 
system manager enables NSP. 


MISSING SPECIAL FEATURE 


DECnet was not installed at system generation time. The network functions 
cannot be executed. 


The following example disconnects logical link 255 and includes user data 


explaining 
have to be 


the reason for disconnecting the link. (The remote program would 
coded to recognize this message and take appropriate action.) 


INTEGER ERRVAL 


. 


CALL NTDI(ERRVAL +255 »"NOMORE" +6 +0) 
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5.6.9 Send Link Abort Message (NTLA) (DECnet) 


The NTLA call is used to terminate a logical link immediately. If there are 
still messages in the transmit queues waiting for acknowledgment from the 
remote NSP, they are discarded. They may or may not have been received by 
the remote system (see Section 3.14). 


Up to 16 bytes of user data can be sent with the message. If the NTLA call is 
issued for an established logical link, the remote system is notified that the 
link has been broken and the user data is delivered to the remote program. If 
the NTLA call is issued for a logical link awaiting confirmation from the 
remote program, the user data does not reach the remote program (see Section 
3.14). 

FORTRAN Call Format: 


CALL NTLA(errval,ula, buffer, buflen, bufoff) 


Argument Descriptions: 


errval 


The errval argument must be an integer variable name. This variable is set to 
zero if the NTLA call succeeds. If an error occurs, errval is set to one of the 
error codes listed under “Possible Errors” at the end of this section. 


ula 


The ula is an integer value identifying the user link address (1 to 255) chosen 
by the calling program in its Connect Initiate (NTCI) or Connect Confirm 
(NTCC) Message sent during the connection sequence. 


buffer 


This argument defines the starting address of a buffer containing optional 
user message data. If a nonzero offset is given (see bufoff), the offset is added 
to the starting address defined by the buffer argument. 


buflen 
This integer value defines the number of bytes of user data to be sent: 0 to 16. 
bufoff 


This integer. value defines an offset, in bytes, from the address specified by the 
buffer argument. The value of bufoff is added to the starting address of the 
buffer to find the beginning address of the user message data. For example, if 
bufoff = 20, the user data begins in byte 21 of.the buffer. 


byte 1 20} 21 (buflen+20) 


whole buffer 
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NOTE 


The FORTRAN interface makes no checks for inconsistencies 
in the buffer, buflen, and bufoff values specified. A program 
could, for example, specify a buflen of 16 and a bufoff of -100. 
Sixteen bytes beginning at buffer-100 would be sent. 


Possible Errors: 


errval 


18 


31 


32 


62 


~8 


Example: 


Error Text and Meaning 


BAD DIRECTORY ON DEVICE 


Network operations have been terminated due to an internal error. Notify the 
system manager. 


CAN’T FIND FILE OR ACCOUNT 


The user link address (ula) specified in the call does not correspond to any known 
logical link for the calling program. Either the ula is incorrect or the logical link 
has been disconnected. In the latter case, a Disconnect or Link Abort Message has 
already been queued for this link. 


ILLEGAL SYS() USAGE 
One of two possibilities: 


1. The calling program is not a declared receiver. A Declare Receiver call must 
be issued before this call is given. 


2. The ula specified is zero. It must be within the range 1 to 255. 
ILLEGAL BYTE COUNT FOR I/O 


The length field passed in buflen is invalid. The length of the buffer must be 
between 0 and 16 for a Link Abort Message. 


NO BUFFER SPACE AVAILABLE 


System buffers are not currently available to store this message. A later try may 
succeed. 


NO RUN-TIME SYSTEM 


NSP has not been enabled. Normal DECnet calls cannot be executed until the 
system manager enables NSP. 


MISSING SPECIAL FEATURE 


DECnet was not installed at system generation time. The network functions 
cannot be executed. 


The following example aborts logical link 17. No user data is sent. 


LOGICAL*1 


’ 


. 


A(256) 


CALL NTLACERRVAL 117+A1010) 
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The MRCV call retrieves a message from the calling program’s pending mes- 
sage queue. It returns control parameters and user data, if any, to buffers 
defined in the call. The Connect Data Block for Connect Initiate Messages is 
also delivered to the buffer that receives the user data. The message data can 
be retrieved all at once or in portions, and portions can be discarded. The 
formats in Sections 5.7.1 - 5.7.9 show what control information is returned for 
the various types of messages. 


A Receive call can be selected to get (1) the first message in the queue, (2) the 
first message in the queue from either a network or a local sender, or (3) the 
first message in the queue for a particular logical link. A sleep flag and 
associated timer can be set to indicate that the calling program is to wait if 
there are no appropriate messages pending in the queue. 


FORTRAN Call Format: 
CALL MRCV(errval,retbuf,rmod,sndr,qual, buffer, buflen, bufoff,siptime) 


Argument Descriptions: 
errval 


The errval argument must be an integer variable name. This variable is set to 
zero if the MRCV call succeeds. If an error occurs, errval is set to one of the 
error codes listed under “Possible Errors” at the end of this section. 


retbuf 


This argument names the starting address of a buffer to contain the control 
information identifying the type and characteristics of the message received. 
The predefined buffer must be at least 40 bytes long. The format of the data 
returned depends on the message type, as described in Sections 5.7.1 - 5.7.9. 


rmod 


The receive modifier (rmod) argument is an integer value consisting of four 
flags:s +¢t+l+n. 


s The sleep flag (s) defines what is to be done if there is no appropriate 
message in the queue for the Receive call to deliver; that is, a message 
of the type requested with the /, n, sndr, and qual arguments. If s =1, 
the program will “sleep” — suspend execution — until something 
happens. The slptime argument regulates the time that the program 
will sleep. 


If the s flag is set to 0, the program will not sleep. If there are no 
appropriate messages in the queue, the call terminates immediately 
with errval = 5. : 


Network Programming in FORTRAN 


t The truncate flag (t) is set to 2 to discard any excess information that 
will not fit in the buffer specified in this call. Information could be left 
over if the value of buflen is smaller than the amount of user data in 
the message. 


A 0 value for t indicates that such excess information is kept for 
retrieval on later Receive calls. 


| The local sender flag (I) is set to 4 to select a message from a local 
sender. The selection can be further qualified with the sndr and qual 
arguments. 


If | = 0, local selection is not requested. If both / and n are zero, the 
first message in the queue is returned. 


n The network sender flag (n) is set to 8 to select a message from a 
network sender. The selection can be further qualified with the sndr 
and qual arguments. - 


If n = 0, network selection is not requested. If both / and n = 0, the first 
message pending in the queue is returned. If | = 4, and n = 8, local 
selection prevails. 


sndr 


The sender selection argument (sndr) is an integer value that selects a partic- 
ular local sender or a particular logical link for this Receive call. 


If | = 4 (local selection) and sndr is nonzero, sndr is interpreted as a job 
number times two. The first message on the queue from that particular local 
job is retrieved. 


If | = 0 and n = 8 (network selection), a nonzero value for sndr is interpreted as 
a user link address. The first message on the queue from that logical link is 
delivered. 


If sndr = 0 when either | = 4 or n = 8, the qual argument has special meaning. 
The sndr and qual arguments are ignored if both / and n are zero. 


qual 


The sender selection qualifier (qual) is an integer value — normally zero for 
user applications. 


If | = 4 (local selection) and sndr = 0, then any nonzero value for qual is a 
special-case Receive call, requesting a message from the system (job num-ber 
0). This special case is used by the RSTS/E utility ERRCPY, that processes 
messages from the monitor error logging routines. 


The qual argument is ignored if both / and n = 0 or if sndr + 0. 


Table 5-4 summarizes the relationships between the selection bits of rmod 
and the sndr and qual arguments. 
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Table 5-4: Sender Selection Summary 


rmod 


nol sndr qual Result 


0 0 n/a n/a The sndr and qual values are ignored. The MRCV 
call returns the first message in the pending message 
queue. 


n/a 4 0 0 Selects the first Local Data Message in the queue. 


0 nonzero Selects job 0. This combination is used by the error 
logging programs to select messages from monitor 
error logging routines. 

nonzero n/a Selects Local Data Messages by job number. The 
sndr argument is interpreted as a job number times 2. 
Only messages from that job are delivered on this 
MRCV call. 


8 0 0 n/a Selects the first network message (anything other 
than a Local Data Message). 


nonzero n/a Selects network messages from a particular logical 
link. The sndr argument is interpreted as a user link 
address. Only network messages from the designated 
logical link are delivered on this MRCV call. 


buffer 


This argument defines the starting address of the buffer to which user mes- 
sage data is to be delivered. If a nonzero offset is given (see bufoff), the offset 
is added to the starting address defined by the buffer argument. 


buflen 


This integer argument defines the maximum number of bytes to be delivered 
to the buffer on this Receive call. 


If a program has limited buffer space, the buflen value can be set to process a 
large segment in small pieces. If truncation is not requested (t flag of rmod = 
0) and the amount of data in the message is greater than the amount indi- 
cated by buflen, only the amount indicated by buflen will be returned and the 
rest will be saved for retrieval with later Receive calls. 


The usual sequence in this case is to issue Receive calls until the number of 
bytes remaining in the pending message goes to zero. This point can be deter- 
mined by examining bytes 9-10 in the data returned to the retbuf buffer by 
the Receive call. The number of bytes actually returned to the buffer is re- 
turned in bytes 13-14 in the retbuf buffer. (See the formats in Sections 5.7.1 - 
5.7.9.) : 


bufoff 


This integer value defines an offset, in bytes, from the beginning of the buffer 
specified by the buffer argument. The value of bufoff is added to the starting 


_ buffer address to define the beginning address of the user message data. For 


example, if bufoff = 20, the user message data is delivered beginning in byte . 
21 of the buffer. 
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byte 1 . 20} 21 (buflen+20) 
whole buffer 
NOTE 


The FORTRAN interface makes no checks for inconsistencies 
in the buffer, buflen, and bufoff values specified. A program 
could, for example, specify a buflen of 100 and a bufoff of 20. 
Up to 100 bytes beginning at buffer+20 could be delivered on 
the Receive call. 


siptime 


The siptime argument, an integer value, is significant only when the s flag of 
rmod = 1. In that case, siptime defines the length of time, in seconds, that a 
program is to sleep when no appropriate message is in the queue. The program 
will sleep until: 


The sleep timer expires. 


Any new message is placed in the queue (not just an appropriate one). 


1 

2 

3. A delimiter is typed on a terminal opened by, or assigned to, the job. 
4. Log-ins are disabled. (This could occur if the system is being shut down). 
5 


A state change occurs on a pseudo-keyboard assigned to the job. (The job 
has printed output for the controlling job to read or has entered an input 
wait state.) 


6. The job itself has opened the XM: (DMC11 driver) and a message is 
received for the job. 


In all cases, the program is awakened with an error (errval = 5) but is not 
passed a message. To obtain a pending message, the program must execute 
another Receive call. Since the program can be awakened by any of the. 
conditions listed previously, a check for pending messages can be made by 
executing a MRCV call without a sleep. 


Possible Errors: 


errval Error Text and Meaning 


5 CAN’T FIND FILE OR ACCOUNT 


For a Receive call without sleep (s flag in rmod = 0), this error indicates that no 
appropriate messages are pending. For a Receive call with sleep (s flag in rmod = 
1), this error is returned when the program is awakened from the sleep. The 
program must execute another MRCV call to retrieve any pending messages. 


18 ILLEGAL SYS() USAGE 


No Receiver ID block exists for the calling program. Before any Receive call can 
succeed, a Declare Receiver (MDCL) call must be executed. 
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Example: 


In the following example, the first Receive call is issued for Network Data 
Messages with the sleep bit set and the timer set to five seconds. The truncate 
bit is 0 and the length argument is 0, so all the information that is available is 
saved for the second Receive call. The test for ERRVAL = 5 after the first 
Receive call (with sleep) ensures that a message is waiting when the second 
Receive call is issued. The computed GO TO checks byte 3 of the returned 
data that identifies the type of message and branches accordingly. Since this 


byte is a signed value, it is not necessary to convert it to an integer. 


119 


120 


130 
200 
300 


LOGICAL#1 RETBUF (40) »BUFFER(256) 
INTEGER S»NeERRVAL »RMOD »SLPTIM 


Ss =i 

N= 8 

ERRVAL = 0 
RMOD = S + N 
SLPTIM = 5 


CALL MRCV(ERRVAL »RETBUF »RMOD -0.0 »BUFFER +0 +0 +SLPTIM) 

IF ERRVAL .EQ. 5S GOTO 110 

RMOD = N 

CALL MRCVCERRVAL »-RETBUF »RMOD 00 ,BUFFER »256 19 50) 

IF ERRVAL .NE. 0 GOTO 4000 

GO TO (200,300 »400 +500 +600 +700 »800 190051000) RETBUF(3)+10 
(processing for Link Abort Message) 

(processing for Disconnect Message) 
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5.7.1 Format of Received Local Data Message 


The format of the i 


nformation returned to the retbuf buffer for a Local Data 


Message is shown below. Up to 512 bytes of user data can be delivered to the 
data buffer specified in the Receive (MRCV) call. 


Bytes 


1-2 
3 


11-12 
13-14 


15-20 
21-40 


Data Type 


integer 


integer 


(however sent) 


Description 


Not meaningful - should be ignored. 
The value -1, function code for a Local Data Message. 
Two times the job number of the local sender. 


The project-programmer number of the local sender. Byte 5 
= programmer number, byte 6 = project number. 


Not meaningful - should be ignored. 


The number of bytes of user data not delivered to the 
buffer. This data has been either discarded or saved for a 
later Receive call, depending on how the ¢ flag was set in 
the rmod argument. 


Not meaningful - should be ignored. 


The number of bytes of user data transferred to the buffer 
on this Receive call. 


Not meaningful - should be ignored. 


The data passed as parameters by the sender of this mes- 
sage. The system pads any unused bytes with binary zeros 
to a length of 20 bytes. 
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5.7.2 Format of Received Connect Initiate Message 


The format of the information returned to the.retbuf buffer for a received 
Connect Initiate Message is shown below. A 120-byte Connect Data Block and 
up to 16 bytes of user data are also returned to the data buffer specified in the 
Receive call. The format of a received Connect Data Block is shown in Figure 
5-2 and described in detail in Table 5-5. 


Bytes 


1-2 


24 


Data Type 


byte 


integer 


integer 


integer 


byte 


Description 


Not meaningful - should be ignored. 
The value -2, function code for a Connect Initiate Message. 
Not meaningful - should be ignored. 


Local link address. Identifies the link in the local program's 
subsequent Connect Confirm or Connect Reject Message. 


Not meaningful - should be ignored. 


The number of bytes of user data not delivered to the 
buffer. This data has been either discarded or saved for a 
later Receive call, depending on how the ¢ flag was set in 
the rmod argument. 


Not meaningful - should be ignored. 


The number of bytes of user data transferred to the buffer 
on this Receive call. 


Not meaningful - should be ignored. 


Remote link modifier. Indicates the flow control in effect tor 
the remote program. The low-order two bits should be 
masked and interpretted as follows: 


LOGICAL*1 RETBUF(40) 
INTEGER RLMOD 


. 


RLMOO = RETBUF (23) 
FLOW = RLMOD .AND. 3 


Then, FLOW = 0, no flow control 
= 1, segment flow control 
= 2, message flow control 


When the byte value RETBUF(23) is stored in the integer 
variable RLMOD, the sign extension is insignificant since 
we are masking off all but the two low-order bits. 


Not meaningful - should be ignored. 


(continued on next page) 
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Bytes Data Type Description 


25-26 integer Receive maximum, in bytes. The maximum amount of user 
data that will be transmitted to the local program in one 
Network Data Message over this link. This value is sup- 
plied by the local NSP and is determined by the size of the 
receive buffers that it allocates. The maximum size of the 
receive buffers is set for NSP by Network Management. 
The program can further limit the amount of user data to 
be received by specifying a smaller rmax in the Connect 
Confirm Message that accepts this request for a logical link 
(see Section 5.6.3). 


27-28 integer Transmit maximum, in bytes. The maximum amount of 
user data that can be transmitted by the program in one 
Network Data Message over this link. This limit has been 
imposed by either the remote program or the remote NSP. 
The local NSP enforces this limit for all Network Data 
Messages sent by the local program on this link. 


29-40 _ Not meaningful - should be ignored. 


REMOTE | REMOTE LOCAL ACCESS CONTROL FIELOS RESERVED 
NODE PROGRAM PROGRAM 


Ary (8) (9) (10) (11) (22) (23) E 















27 | 28 | 29 | 30} 31 42143 46 
F 
ele fe] re 


for local program name 


DECneVE accepts Connect Initiate 
Messages addressed to object type 
code or name — not both 


Legend: 

ai A eal _ 47 | 48 149 64165 | 66 [67 74| 75} 76177 92 
Se fof] sere _[ofiglrsmono| il sar 

sere / 4 N yl INFORMATION 

: supply if needed by remote program 

' = length 


Figure 5-2: Format of Received Connect Data Block 
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Table 5-5: Format of Received Connect Data Block 


Bytes 


1-6 


7=26 


Content 


Remote Node. 1 to 6 uppercase, alphanumeric ASCII characters naming the 
remote node from which the Connect Initiate Message was received. The name 
will contain at least one alphabetic character. Node names shorter than six 
characters will be left-justified and padded to six characters with spaces. 


Remote Program. Identifies the remote program that sent the Connect Initiate 
Message as either an object type (general function) or a specific entity (program, 
task, or process). This identification is given in one of three formats: 


Format 0 
The remote program is identified by object type code alone. The fields are: 
Bytes Content 


7 Zero, to indicate a format 0 name. 
8 Object type code of the remote program. 
9-26 Not meaningful — should be ignored. 


Format 1 
The remote program is identified by a descriptor. The fields are: 
Bytes Content 


7 One, to indicate a format 1 name. 

8 Normally zero. This byte will usually be zero unless the remote 
DECnet system allows identification by both name and object type 
code on outgoing connect requests (DECnet/E does not). If nonzero, 
this byte is interpreted as the object type code of the remote program 
that sent the Connect Initiate Message. 


9 Not meaningful — should be ignored. 

10 Length of descriptor, 0 to 16 bytes. Gives the number of characters to 
be interpreted as the program descriptor in the following field ‘bytes 
11-26). 


11-26 Remote program descriptor (left-justified). The descriptor used to reg- 
ister the remote program for network operations. For remote DECnet/E 
systems, this is the logical name declared in the Declare Receiver call. 


Format 2 


This format identifies the remote program by name or object type code and by 
the group and user codes under which the remote program is running on the 
remote system. (The group and user codes refer to what is called the project- 
programmer number on some DIGITAL systems, including RSTS/E. Other sys- 
tems refer to these codes as the user identification code, or UIC.) DECnet/E 
systems use this format to identify the sender of a Connect Initiate Message. 


The subfields are defined as follows: 
Bytes Content 


7 Two, to indicate a format 2 name. 

8 Object type code of the remote program, if ssolCable: If zero, the 
descriptor alone identifies the remote program. 

9 Not meaningful — should be ignored. 

10 Length of descriptor, 0 to 12 bytes. Gives the number of characters to _ 
be interpreted as the program descriptor in the following field (bytes 
11-22). 


(continued on next page) 
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Table 5-5 (cont.): Format of Received Connect Data Block 


Bytes Content 


11-22 Remote program descriptor, if this is used instead of object type code. 
The descriptor will be left-justified ASCII characters. 

23-24 Remote group code. Binary value giving the group number under which 
the remote program is running. If the remote system is a DECnet/E 
system, byte 23 is the project number in a project-programmer number. 

25-26 Remote user code. Binary value giving the user number under which 

- the remote program is running. If the remote system is a DECnet/E 
system, byte 25 is the programmer number in a project-programmer 
number. 


27-46 Local Program. This field indicates how the remote program addressed the 
local program in the Connect Initiate Message. DECnet/E allows the local pro- 
gram to be addressed by object type code or by name, but not both. Again, three 
formats can be used. The subfields are as follows: 


Bytes Content 


. 27 Format type. Equal to 0, 1, or 2, depending on the format used by the 
remote program to address the local one. 

28 Object type code, if used by the remote program to address the local 
program (formats 0 or 2). 

29 Always zero. 

30 Length of name, in bytes. Will be 0 for format 0, 1 to 6 for format 1, 0 to 
6 for format 2. (DECnet/E program names are limited to a maximum of 
six characters by the Declare Receiver call.) 

31-36 Local program name, if used by the remote program to address the 
local program (formats 1 or 2). 

37-42 Always zero. 

43-44 Local group code. Binary value giving the local program’s project 
number, if used by the remote program to address the local program 
(format 2). Zero otherwise (formats 0 or 1). Not used by NSP to iden- 
tify the local program but passed on here. 

45-46 Local user code. Binary value giving the local program's programmer 
number, if used by the remote program to address the local program 
(format 2). Zero otherwise (formats 0 or 1). Not used by NSP to iden- 
tify the local program but passed on here. 


47-92 Access Control Fields. These bytes can be used to define the remote program's 
access rights to the local program’s services. The idea is analogous to logging in 
to the local system. The most rigorous checking done in a normal log-in on 
DIGITAL systems involves user identification, password, and account number, 
so three fields are defined here for those items. However, overall DECnet design 
does not specifically require use of these fields at all, nor does it require that the 
fields be used as described. A DECnet/E system simply passes this information 
on to the receiving program. 


Bytes Content . E 


47 Not meaningful — should be ignored. 
48 Length of user identification information specified in the next field, 0 
to 16 bytes. : 


49-64 User Identification. This field identifies the person or program re- 
questing the logical link. In RSTS/E terms, the user ID is analogous to 
the project-programmer number used at log-in. 

65 Not meaningful — should be ignored. 

(continued on next page) 
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Table 5-5 (cont.): Format of Received Connect Data Block 


Bytes Content 


66 Length of password information specified in the next field, 0 to 8 bytes. 

67-74 Password. A password is often used to verify access to a system under a 
particular user identification. In RSTS/E, this password is analogous to 
the password used in conjunction with the project-programmer number 


used at log-in. 

75 Not meaningful — should be ignored. 

76 Length of the accounting information specified in the following field, 0 
to 16 bytes. 


77-92 Accounting information. Many systems require a billing account 
number in addition to user identification and password. The ac- 
counting field is provided for this purpose. 


93-120 Reserved for future use. Should be ignored. 
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5.7.3 Format of Received Connect Confirm Message 


A received Connect Confirm Message is a remote program’s acceptance of a 
Connect Initiate Message sent by the local program. The link is identified by 
the user link address specified by the local program in the Connect Initiate 
Message. The format of the information returned to the retbuf buffer is de- 
scribed below. Up to 16 bytes of user data can also be returned to the data 
buffer specified in the Receive call. 


Bytes Data Type Description 

1-2 _ Not meaningful - should be ignored. 

3 byte The value -3, function code for a Connect Confirm Mes- 

; sage. 
4 byte User link address, previously defined in the local program's 
Connect Initiate Message. 
5-8 _ Not meaningful - should be ignored. 
9-10 integer The number of bytes of user data not delivered to the data 


buffer. This data has been either discarded or saved for a 
later Receive call, depending on how the ¢ flag was set in 
the rmod argument. 


11-12 _ Not meaningful - should be ignored. 

13-14 integer The number of bytes of user data transferred to the data 
buffer on this Receive call. 

15-22 - Not meaningful - should be ignored. 

23 byte Remote link modifier. Indicates the flow control in effect for 


the remote program. The low-order two bits should be - 
masked and interpretted as follows: 


LOGICAL#1 RETBUF(40) 
INTEGER RLMOD »FLOW 


. 


RLMOD = RETBUF (23) 
FLOW = RLMOD .AND. 3 


Then FLOW = 0, no flow control 
= 1, segment flow control 
= 2, message flow control 


24 - Not meaningful - should be ignored. 


(continued on next page) 
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Bytes 


25-26 


27-28 


29-40 


Data Type 


integer 


integer 


Description 


Receive maximum, in bytes. The maximum amount of user 
data that will be transmitted to the local program in one. 
Network Data Message over this link. This will be (1) equal 
to the rmax value specified by the local program in the 
Connect Initiate Message for this link, or (2) a lesser value 
supplied by the local NSP, determined from the size of the 
receive buffers it allocates. 


Transmit maximum, in bytes. The maximum amount of 
user data that can be transmitted by the local program in 
one Network Data Message over this link. This limit has 
been imposed by either the remote program or the remote 
NSP. The local NSP enforces this limit for all Network 
Data Messages sent by the local program on this link. 


Not meaningful - should be ignored. 
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5.7.4 Format of Received Connect Reject Message 


A received Connect Reject Message is a rejection of the local program’s re- 


quest for a logical link. 
remote NSP. The link 


It can be from the remote program or from the local or 
is identified by the user link address previously estab- 


lished in the local program’s Connect Initiate Message. The format of the 
information returned to the retbuf buffer is described below. Rejections from 
NSP will contain a reason code explaining the reason for the rejection and will 
not contain user data. Rejections from the remote program can contain up to 
16 bytes of user data, delivered to the data buffer defined in the Receive call. 


Bytes 


1-2 


Data Type 


Description 


Not meaningful - should be ignored. 
The value -4, function code for a Connect Reject Message. 


User link address, previously defined in the local program's 
Connect Initiate Message. 


Not meaningful - should be ignored. 


The number of bytes of user data not delivered to the data 
buffer. This data has been either discarded or saved for a 
later Receive call, depending on how the ¢ flag was set in 
the rmod argument. 


Not meaningful - should be ignored. 


The number of bytes of user data transferred to the data 
buffer on this Receive call. 


Not meaningful - should be ignored. 
Identifies the reason for the rejection (see Appendix B). 
Not meaningful - should be ignored. 
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5.7.5 Format of Received Network Data Message 


A received Network Data Message contains user data from a remote program. 
The format of the information returned to the retbuf buffer is described 
below. The user data accompanying the Network Data Message is delivered to 
the data buffer specified in the Receive call. 


Bytes 


1-2 
3 
4 


5-8 
9-10 


11-12 
13-14 


15-20 
21 


22-40 


Data Type 


byte 


integer 


integer 


byte 


Description 


Not meaningful - should be ignored. 
The value -5, function code for a Network Data Message. 


User link address, previously defined in the local program's 
Connect Initiate or Connect Confirm Message. 


Not meaningful -. should be ignored. 


The number of bytes of user data not delivered to the data 
buffer. This data has been either discarded or saved for a 
later Receive call, depending on how the ¢ flag was set in 
the rmod argument. 


Not meaningful - should be ignored. 


The number of bytes of user data transferred to the data 
buffer on this Receive call. 


Not meaningful - should be ignored. 


Data message flags. The low-order bits indicate whether 
this is the beginning, middle, end, or sole segment of a 
logical message. These bits should be masked and inter- 
pretted as follows: 


BYTE RETBUF (40) 
INTEGER OMFLGS+60M,EOM 


OMFLGS = RETBUF (21) 
BOM = OMFLGS .AND,. 1 
EOM = DMFLGS .AND. 2 


Then 
eom bom 
0 0 Middle segment of message 
0 1 First segment of message 
2 0 Last segment of message 
2 1 Sole segment of message 


If the local program requested message flow control when 
the logical link was established, DECnet/E uses the EOM 
bit to determine the end of a logical message. It does not 
use the BOM bit but passes it on to the receiving program. - 


Not meaningful - should be ignored. 
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5.7.6 Format of Received Interrupt Message 


The local NSP places Interrupt Messages from a remote program at the head 
of the pending message queue, behind the first message and behind any other 
pending Interrupt Messages queued for the program. The format of the data 
returned to the retbuf buffer is described below. Up to 16 bytes of user data 
can be delivered to the data buffer specified in the Receive call. 


Bytes Data Type Description 

1-2 _ Not meaningful - should be ignored. 

3 byte The value -6, function code for an Interrupt Message. 

4 byte User link address, previously defined in the local program's 
Connect Initiate or Connect Confirm Message. 

5-8 - Not meaningful - should be ignored. 

9-10 integer The number of bytes of user data not delivered to the 


buffer. This data has been either discarded or saved for a 
later Receive call, depending on how the ¢ flag was set in 
the rmod argument. 


11-12 _ Not meaningful - should be ignored. 


13-14 integer The number of bytes of user data transferred to the buffer 
on this Receive call. 


15-40 _ Not meaningful - should be ignored. 
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5.7.7 Format of Received Link Service Message 


A Link Service Message provides status information for a particular logical 
link. A Link Service Message is only returned on a Receive call when the 
pending message queue has emptied after a condition has cleared that previ- 
ously inhibited the local program from sending (see Section 4.2). Status infor- 
mation with the same format as a Link Service Message can also be returned 
to the retbuf buffer on successful completion of a Send Link Service, Send 
Network Data, or Send Interrupt call. The format of the information returned 
is described below. No data is delivered to the data buffer with a Link Service 
Message. 


Bytes Data Type Description 

1-2 — Not meaningful - should be ignored. 

3 byte The value -7, function code of a Link Service Message. 

4 byte User link address, previously defined in the local program's 
Connect Initiate or Connect Confirm Message. 

5-8 _ Not meaningful - should be ignored. 

9-10 integer Always zero for Link Service. (These bytes are the re- 
mainder field in other returned messages.) 

11-12 _ Not meaningful - should be ignored. 

13-14 integer Always zero for Link Service. (These bytes are the length 
field in other returned messages.) 

15-20 - Not meaningful - should be ignored. 

21 byte Local status flags. These flags should be masked and inter- 


pretted as follows: 


LOGICAL*1 RETBUF (40) 
INTEGER LSTAT »DATA,INTLS »LCLBP 


° 


LSTAT =.RETBUF (21) 
DATA = LSTAT .AND. 1 
INTLS = LSTAT .AND. 2 
LCLBP = LSTAT .AND. 192 


If DATA = 1, outgoing Network Data Messages are inhib- 
ited. (A Link Service Message will be delivered when the 
condition clears.) 


If INTLS = 2, outgoing Interrupt and Link Service Mes- 
sages are inhibited. (A Link Service Message will be deliv- 
ered when the condition clears.) 


The LCLBP value indicates the local NSP’s backpressure 
status for this link: 


(continued on next page) 
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Bytes 


22 


24 


26 


Data Type 


byte 


byte 


byte 


byte 


byte 


Description 


LCLBP 
0 Incoming Data Message flow is on. 


64 Incoming Data Message flow is on but the 
local NSP will turn this link off if another 
Data Message is received before the local pro- 
gram’s receive queue is emptied. 


128 - Incoming Data Message flow has been turned 
off by the local NSP. The local program’s re- 
ceive queue must be emptied before the link 
will be turned on. 


192 Incoming Data Message flow has been turned 
off by the local NSP but flow is scheduled to 
turn on as soon as system buffers become 
available. 


Remote status flags. Only one bit is currently defined for 
this field. This bit should be masked and interpretted as 
follows: 


LOGICAL#1 RETBUF(40) 
INTEGER REMBP »RSTAT 


RSTAT = RETBUF (22) 
REMBP = RSTAT .AND. 128 


If REMBP = 128, the link has been turned off by the remote 
system due to a backpressure condition. No Data Messages 
can be sent until the remote system turns the link back on. 


Local data request count. The count of segments or logical 
messages currently requested by the local program, re- 
flecting the actual number of segments or logical messages 
requested but not yet received. 


Local interrupt request count. The count of Interrupt Mes- 
sages currently requested by the local program, reflecting 
the actual number of Interrupt Messages requested but not 
yet received. This count will never exceed cne. 


Remote data request count. The count of segments or log- 
ical messages currently requested by the remote program, 
reflecting the actual count of segments or messages re- 
quested but not yet sent. 


Remote interrupt request count. The count of Interrupt 
Messages currently requested by the remote end of the log- 
ical link, reflecting the actual count of Interrupt Messages 
requested but not yet sent. 


(continued on next page) 
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Bytes 


27 


28 


29 


30 


31 


32 


33 


34-40 


Data Type 


byte 


byte 


byte 


byte 


Description 


Data transmit queue maximum. The maximum number of 
data messages that can be queued waiting for acknowledg- 
ment from the remote system. This is a constant set by the 
system manager when NSP is enabled. It applies individu- 
ally to all active logical links. 


Data transmit queue count. The number of Data Messages 
currently in the data transmit queue for this local link. It is 
a count of data messages waiting for acknowledgment from 
the remote NSP. 


Interrupt/Link Service transmit queue maximum. The 
maximum number of Interrupt or Link Service Messages 
that can be queued waiting for acknowledgment from the 
remote system. This is a constant set by the system man- 
ager when NSP is enabled. It applies individually to all 
active logical links. : 


Interrupt/Link Service transmit queue count. The number 
of Interrupt and Link Service Messages currently in the 
Interrupt/Link Service transmit queue for this logical link. 
It is a count of Interrupt and Link Service Messages waiting 
for acknowledgment from the remote NSP. 


Message maximum. The maximum number of incoming 
messages that will be queued for the local program. This 
maximum is set by the program in its Declare Receiver call. 


Message count. The total number of messages currently in 
the pending message queue for the local program. 


Message count for this logical link. The number of mes- 
sages currently in the pending message queue for the logical 
link identified by the ula in byte 4. 


Not meaningful - should be ignored. 
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5.7.8 Format of Received Disconnect Message 


A received Disconnect Message indicates that an established logical link has 
been disconnected by the remote program. All other messages sent by the 
remote program over this logical link have been received by the local program. 
The format of the data returned to the retbuf buffer is defined below. Up to 16 
bytes of user message data can be returned to the data buffer specified in the 
Receive call. 


Bytes 


1-2 
3 
4 


5-8 


Data Type 


integer 


integer 


Description 


Not meaningful - should be ignored. 
The value -8, function code for a Disconnect Message. 


User link address, previously defined in the local program’s 
Connect Initiate or Connect Confirm Message. 


Not meaningful - should be ignored. 


The number of bytes of user data not delivered to the data 
buffer. This data has been either discarded or saved for a 
later Receive call, depending on how the ¢ flag was set in 
the rmod argument. 


Not meaningful - should be ignored. 


The number of bytes of user data transferred to the data 
buffer on this Receive call. 


Not meaningful - should be ignored. 
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5.7.9 Format of Received Link Abort Message 


A received Link Abort Message indicates that a logical link has been termi- 
nated by the remote program or by the local or remote NSP. The format of the 
data returned to the retbuf buffer is defined below. Up to 16 bytes of user 
message data can be returned to the data buffer specified in the Receive call. 


Bytes Data Type 
1-2 - 

3 byte 

4 byte 
5-6 integer 
7-8 _ 
9-10 integer 
11-12 — 
13-14 integer 
15-22 — 
23-24 integer 
25-40 —_ 


Description 


Not meaningful - should be ignored. 
The value -9, function code for a Link Abort Message. 


User link address (if any), previously defined in the local 
program’s Connect Initiate or Connect Confirm Message. 


Local link address, established by the local NSP for this 
link. It identifies the link if the remote program has sent a 
Connect Initiate Message but the local program has not yet 
responded with a Connect Confirm or Connect Reject Mes- 
sage. No ula exists under these conditions to identify the 
link being aborted. 


Not meaningful - should be ignored. 


The number of bytes of user data not delivered to the data 
buffer. This data has been either discarded or saved for a 
later Receive call, depending on how the ¢ flag was set in 
the rmod argument. 


Not meaningful - should be ignored. 


The number of bytes of user data transferred to the data 
buffer on this Receive call. 


Not meaningful - should be ignored. 


Abort reason. If this is nonzero, the link was aborted by 
either the local or remote NSP and the reason is specified in 
these two bytes. The reasons that apply for a link abort are 
listed in Appendix B. If reason is zero, the link was aborted 
at the request of the remote program. 


Not meaningful - should be ignored. 
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Appendix A 


Object Type Codes 


023 


Type of Process 


General Task, User Process 

File Access (FAL/DAP Version 1) 

Unit Record Services (URD) 

Application Terminal Services (ATS) 
Command Terminal Services (CTS) 
RSX-11M Task Control, Version 1 
Operator Services Interface 

Node Resource Manager 

IBM 3270-BSC Gateway 

IBM 2780-BSC Gateway 

IBM 3790-SDLC Gateway 

TPS Application 

RT-11 DIBOL Application 

TOPS-20 Terminal Handler 

TOPS-20 Remote Spooler 

RSX-11M Task Control, Version 2 

TLK Utility (LSN on DECnet/E) 

File Access (FAL/DAP Version 4 and later) 
RSX-11S Remote Task Loader 

Network Management Listener (NICE Process) 
RSTS/E Media Transfer Program (NETCPY) 
Reserved for DECnet use 

Mail Listener 

Host Terminal Handler (NPKDVR) 


(continued on next page) 
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A-2 


Code 


Type of Process 


Concentrator Terminal Handler 
Loopback Mirror 

Event Receiver 

VAX/VMS Personal Message Utility 
File Transfer Spooler (FTS) 
Reserved for DECnet use 

DECnet test tool (DTR) 

Reserved for DECnet use 


Reserved for customer extensions 
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Appendix B 


NSP Reason Codes for Connect Reject and Link 
Abort 


Reason 


No error — user-initiated reject or abort 
Resource allocation failure 

Destination node does not exist 

Node shutting down 

Destination program does not exist 

Invalid destination name or source name field 
Destination program’s queue full 

Unspecified error condition 

Third party aborted logical link 
User-initiated link abort 


SEESEEERREE F 
8 ® 


Reserved 
021 Invalid destination address in Connect Initiate Message 
022 Invalid destination address in Connect Confirm Message 
023 Source address zero in Connect Initiate or Connect Confirm Message 
024 Flow control violation — invalid request count in Link Service Message 
025-031 Reserved 
032 Too many connects to node 
033 Too many connects to destination program 
034 Access not permitted 
035 Logical link services mismatch 
036 Invalid accounting information 
037 Segment size too small 


038 User aborted, timed out, or canceled link 


(continued on next page) 
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Code Reason 


039 _ No path to node 

040 Flow control failure — data received when request count zero 
041 No current link (cannot recognize destination address) 

042 Confirmation from remote system of Disconnect Message 
043 Image data field too long 
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INDEX 


A 


Access, : 
consistency with receiver identity, 5-7 to 5-8 
specifying, 5-6 to 5-8 
types permitted, 5-6 
Access control fields, 5-25 to 5-26, 5-61 to 5-62 
Accounting information, 5-26, 5-33, 5-62 
Adjacent node, 1-1, 1-4 
Automatic startup, 3-6, 4-3, 4-3, 4-5 to 4-6 
ordering of objects, 4-5 
starting line number, 4-5 
timing, 4-6 


Backpressure flow control, 4-13 to 4-14 
clearing, 4-13 
effect on DECnet/E programs, 4-13 
use of Link Service Message, 4-13 
Buffer, 
allocating, 5-2 
declared maximum, 5-8 
limited space, 5-22, 5-30, 5-54 
monitor pool, 2-8, 3-2, 3-4, 3-5, 5-8 
NSP maximum, 3-7 


Cc 


Codes, 
Object type codes, A-1 
Reason codes, B-1 

Compiling, 5-3 
F4P (FORTRAN-IV-PLUS), 5-3 
FORTRAN, 5-3 

Connect Confirm Message, 3-8 to 3-9 
received format, 5-63 to 5-64 
send call, 5-29 to 5-32 

Connect Data Block, 3-6, 3-7, 4-6, 5-2, 5-22, 5-23 

to 5-26, 5-50 to 5-62 

Connect Initiate Message, 3-6 to 3-8 
local program identification, 5-25, 5-61 
received format, 5-58 to 5-62 
remote program identification, 5-24, 5-60 
send call, 5-21 to 5-28 

Connect Reject Message, 3-9 
received format, 5-65 
send call, 5-33 to 5-35 

CORCMN, 4-5 

Core common, 4-5 

Cost, 1-4 

CRC, 1-3 

CTRL/C, 3-5 

Cyclic Redundancy Check, 
See CRC 


DAP, 1-4 
Data Access Protocol, 
See DAP 
Data transmit queue, 4-10 to 4-12, 5-47, 5-50, 5-70 
DDCMP, 1-3, 1-5 
Declare Receiver, 3-2, 3-3 to 3-5 
access, 5-6 to 5-8 
declaring intended usage, 3-4 
link maximum, 3-4 
message maximum, 3-4 
receiver identity, 
See Receiver identity 
sleep bit, 5-7 
system call, 5-5 to 5-10 
Default project-programmer number, 3-5, 4-6, 5-12 
DEFINE OBJECT, 4-5 
Device controllers, 1-5 
DIGITAL Data Communications Message Protocol, 
See DDCMP 
DIGITAL Network Architecture, 
See DNA 
Disconnect Message, 3-11 
affected by transmit queues, 4-11 
received format, 5-71 
send call, 5-47 to 5-49 
DMx controllers, 1-5 
DNA, 1-2, 1-3, 3-6, 5-14 


E 
, End node, 1-4 
EQUIVALENCE statement, 5-3 
ERRCPY, 5-53 
Errors, 


Declare Receiver, 5-9 to 5-10 

Get Local Node Parameters, 5-13 

Log User Event, 5-16 

Receive, 5-55 

Remove Receiver, 5-11 

Send Connect Confirm Message, 5-31 

Send Connect Initiate Message, 5-26 to 5-27 

Send Connect Reject Message, 5-34 to 5-35 

Send Disconnect Message, 5-48 to 5-49 

Send Interrupt Message, 5-41 to 5-42 

Send Link Abort Message, 5-51 

Send Link Service Message, 5-44 to 5-45 

Send Local Data Message, 5-19 to 5-20 

Send Network Data Message, 5-38 to 5-39 
Events, 

See User events 


F 


F4P compiler (FORTRAN-IV-PLUS), 5-3 
File Access Listener, 
See NFT/FAL 
Flow control, 2-8, 3-9, 4-9 to 4-21 
backpressure, 
See Backpressure flow control 
Interrupt Message, 
See Interrupt Message flow control 
local congestion, 4-19 
local modifier, 5-21, 5-29 
program regulated, 
See Program-regulated flow control 
programming hints, 4-19 to 4-21 
reasons for inhibiting transmission, 4-19 
remote congestion, 4-19, 4-21 
remote modifier, 5-58, 5-63 
transmit queue management, 
See Transmit queue management 
use of Link Service Message, 4-21 
FORTRAN compiler, 5-3 
FORTRAN-IV-PLUS compiler (F4P), 5-3 
Full duplex transmission, 2-3 


H 


Hollerith constants, 5-2 
Hop, 1-2 


INTEGER*2 variables, 5-2, 5-2 
INTEGER*“4 variables, 5-2 
Interrupt Message, 2-7, 3-10 
queuing, 2-7, 3-10, 5-40, 5-67 
received format, 5-67 
reenabling, 3-10, 3-10, 4-17 
request count, 4-17 to 4-19, 5-44, 5-69, 5-69 
send call, 5-40 to 5-42 
Interrupt Message flow control, 3-10, 4-17 to 4-19 
effect on DECnet/E programs, 4-17 
use of Link Service Message, 4-17 
Interrupt/Link Service queue, 4-10, 5-47, 5-50, 5-70 
Interrupts, 
See Interrupt Message 
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J 
Job, 
determining number, 4-2 
killing, 4-6 


number in Receive, 5-53 

number of local receiver, 3-6, 5-18 
privilege level, 4-6 

Receiver ID Block, 3-4 to 3-5, 5-5 
receiving from system job 0, 5-53 
Remove Receiver, 3-5, 5-11 


K 
Killing a job, 4-6 
L 
Link 
logical, 
See Logical link 


physical, 1-1, 1-3, 1-5, 2-1 
LINK (FORTRAN linker), 5-4 
Link Abort Message, 3-11 to 3-12 
received format, 5-72 
send call, 5-50 to 5-51 
unaffected by transmit queues, 4-11 
Link master, 2-2 
Link Service Message, 3-10 to 3-11 
purpose, 3-10, 4-13, 4-15, 4-17, 4-17, 5-43 
received format, 5-68 to 5-70 
send call, 5-43 to 5-46 
Link status bit, 5-37, 5-40, 5-44 
Link status flags, 
local, 5-68 
remote, 5-69 
Link status information, 3-9 to 3-10, 3-10, 5-2 to 
5-3, 5-68 
Linking, 5-4 
LINK, 5-4 
TKB, 5-4 
LLA, 2-5, 3-7, 3-8, 3-9, 3-12 
Local communication, 3-1, 3-3, 3-6, 5-18 
Local Data Message, 3-6 
received format, 5-67 
send call, 5-18 to 5-20 





Local link address, 
See LLA 

Local link status flags, 5-68 

Local node, 1-1, 3-5 

Local node parameters, 3-2, 3-5 
system call, 5-12 to 5-13 
use, 4-6 

Local program, 3-3, 3-4 
identification, 5-25, 5-61 


Log-in information, 3-6, 4-6, 5-25 to 5-26, 5-61 to 


5-62 

Logical full duplex transmission, 2-3 

Logical link, 2-1 
aborting, 
See Link Abort Message 
accepting, 
See Connect Confirm Message 
active, 3-5 
creating, 2-2 


declared maximum, 3-4, 4-3, 4-3, 5-6, 5-7, 5-9 


declared message maximum, 3-4, 4-3, 5-8 to 
5-9, 5-70 
DECnet/E limitations, 2-8 
disconnecting, 
See Disconnect Message 
efficient line usage, 2-5 
identifiers, 2-2, 2-5 
message count, 5-70 
message streams, 2-6, 3-10 
receive maximum, 
See Receive maximum 
rejecting, . 
See Connect Reject Message 
requesting 
See Connect Initiate Message 
transmit maximum, 
See Transmit maximum 
Logical message, 4-15, 5-36, 5-43, 5-66 
end of message segment, 4-16 
request count, 4-16, 5-44, 5-69, 5-69 
LOGICAL*1 variables, 5-2, 5-3 


MACRO-11 subroutines, 1-4, 4-2, 4-5, 4-6, 5-1 
Master-slave communication, 3-11, 5-47 
MDCL call, 

See Declare Receiver 


Message, 
count for logical link, 5-70 
count of pending messages, 5-70 
declared maximum, 3-4, 4-3, 4-3, 5-9, 5-70 
limit of transmit queues, 4-11 
logical, 
See Logical message 
request count, 4-16 
Message flow control, 4-15 
Message streams, 2-5, 2-6, 3-10 
MRCV call, 
See Receive 
MREM call, 
See Remove Receiver 
MSLD call, 
See Local Data Message 
Multiple copies of objects, 3-4, 4-2, 4-4 
under BATCH, 4-4 
via automatic startup, 4-4 
via terminal users, 4-4 
Multipoint lines, 1-5 


NCP, 1-4, 1-5, 4-5, 4-10 
NET, 1-4 
NETCPY, 1-4, 4-7 
Network, 1-1, 1-2 
Network addressing, 3-3, 4-1 to 4-8 
declaring identity, 
See Receiver identity 
handling incoming requests, 4-2 to 4-3 
permitted by DECnet/E, 4-2 
to name, 4-2 to 4-3 
to object type code, 4-2 to 4-3 
Network Command Terminal Utility, 
See NET 
Network Communication Utility, 
See TLK/LSN 
Network Control Program, 
See NCP 
Network Copy Utility, 
See NETCPY 
Network Data Message, 3-9 to 3-10 
received format, 5-66 
send call, 5-36 to 5-39 
Network diameter, 1-2 
Network File Transfer, 
See NFT/FAL 


index. 


4 


Network Information and Control Exchange 


Protocol, 

See NICE 
Network program, 3-3, 3-4 
Network Services Protocol, 

See NSP 
NFT/FAL, 1-4, 4-6, 5-7, 5-33 
NICE, 3-6, 5-14, 5-15 
Node, 1-1 

address, 3-5, 5-12 

adjacent, 1-1, 1-4 

alias, 3-5, 5-12 

local, 1-1, 3-5 

name, 3-5, 5-12, 5-23, 5-60 

nonrouting, 1-4 

parameters, 

See Local node parameters 

Phase II, 1-4 

remote, 1-1 

routing, 1-4 
Nonrouting node, 1-4 
NSP, 1-3, 1-4, 2-1 
NTCC call, -. 

See Connect Confirm Message 
NTCI call, 

See Connect Initiate Message 
NTCR call, 

See Connect Reject Message 
NTDI call, 

See Disconnect Message 
NTDM call, 

See Network Data Message 
NTIN call, 

See Interrupt Message 
NTLA call, 

See Link Abort Message 
NTLS call, 

See Link Service Message 


Object, 
automatic startup, 
See Automatic startup 
identification, 
See Receiver identity 
multiple copies, 
See Multiple copies of objects 
type code, 
See Receiver identity 
Object type codes, A-1 
One-shot bit, 5-7 
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See Local node parameters 
output, 5-2 


with DEFINE or SET OBJECT, 4-5 


Password, 5-26, 5-33, 5-62 
Path, 1-2 
Path length, 1-2 
Pending message queue, 2-6, 2-8, 
3-11, 3-12, 4-13 
Phase II, 1-3 to 1-4 
node, 1-4 
Phase III, 1-3 to 1-4 
Physical link, 1-1, 1-3, 1-5, 2-1 
Point-to-point lines, 1-5 
PPN, 5-24, 5-25, 5-33, 5-60, 5-61 
default, 3-5, 4-6, 5-12 
Priority message, 
See Interrupt Message 
Privileged job, 4-6 
Program, 
local, 3-3, 3-4 
network, 3-3, 3-4 
remote, 1-1 
source, 2-2 
target, 2-2 


3-2, 3-5, 3-11. 


Program-regulated flow control, 2-8, 4-15 to 4-17 
effect on DECnet/E programs, 4-15, 4-16 


message, 
See Message flow control 
segment, 
See Segment flow control 


selection, 3-7, 3-8, 4-15, 5-21, 5-29, 5-58, 5-63 
use of Link Service Message, 4-15, 4-17 


Project-programmer number, 
See PPN 

Protocols, 1-3 
DAP, 1-4 
DDCMP, 1-3, 1-5 
NICE, 3-6, 5-14, 5-15 
NSP, 1-3 
Transport, 1-3 


Q 


Queue, 


Data transmit, 4-10, 5-47, 5-50, 5-70 
Interrupt/Link Service, 4-10, 5-47, 5-50, 5-70 


management, 4-10 to 4-12 

message limit, 4-11 

pending message, 2-6, 2-8, 3-2 
4-13 


, 3-5, 3-11, 3-12. 


Segment 
Reason code, B-1 nt, 
for Cor.nect Reject, 3-9, 5-33, 5-65 oe of message, 5-36, 5-66 
for Link Abort, 3-12, 5-72 efinition, 4-15 
Receive, 3-2 end of message, — 5-36, 5-66 
ive, 3-3, 3-11, 3-12, 5-52 to 5-54 Maximum size, 
ayeap Eee ad : request count, 4-16, 5-44, 5-69, 5-69 
systern call 5-52 Segment flow control, 4-15 : 
truncation of message, 3-3, 5-53, 5-54 Selective receives, 3-3, 3-11, 3-12, 5-52 to 5-54 
i imum, 3-7, 3-7, 3-8, 3-10, 5-22, 5-30, Send, 3-2 
sergers ma SET EXECUTOR, 4-10 
Received formats, ae OBJECT, 4-5 
Connect Conform Message, 5-63 to 5-64 eep, 
Connect Initiate Message, 5-58 to 5-62 in Declare Receiver, 5-7 


in Receive, 3-3, 5-52 


, 5-65 
Connect Reject Message Sleep monitor call, 5-7 


Disconnect Message, 5-71 


Interrupt Message, 5-67 Source program, 2-2 
Link Abort Message, 5-72 Starting line number, 4-5 
Link Service Message, 5-68 to 5-70 Strings, 
Local Data Message, 5-57 defining, 5-2 a 
Network Data Message, 5-66 System buffer space, 2-8, 3-2, 3-4, 3-5, 5-8 
Receiver access, System calls, 
See Access general form, 5-1 
Receiver ID Block, summary, 3-1 to 3-2 
See RIB P System library, 5-4 
Receiver identity, 2-6, 3-3 to 3-4, 3-7 System manager, 1-4, 1-5, 2-8, 4-1, 4-3, 4-4, 4-5, 


consistency with access, 5-7 to 5-8 4-7, 4-8, 4-11, 5-14 


declaring, 4-1 to 4-2 
name, 3-3, 4-1, 5-5, 5-18 
object type code, 3-4, 4-1, 5-5 to 5-6, A-1 


object type code, 3-4, 4-1, 5-5 to 5-6, A-1 T 
uniqueness, 4-2 
Receiver name, Target program, 2-2 
See, Receiver identity Task Builder (TKB), 5-4 
Remote link address, Terminal Communication Utility, 
See RLA See TLK/LSN 
Remote link status flags, 5-69 Timing, 
Remote node, 1-1 automatic startup, 4-6 
Remote program,' _ transmit queue management, 4-10 
definition, 1-1 TKB (Task Builder), 5-4 
identification, 5-23, 5-60 TLK/LSN, 1-4 
Remove Receiver, 3-2, 3-5 Transmit maximum, 3-7, 3-9, 3-9, 5-22, 5-30, 5-59, 
system call, 5-11 5-64 
RIB, 3-4 to 3-5, 3-5, 4-2, 4-3, 4-13, 5-5 Transmit queue management, 4-10 to 4-12 
RLA, 2-5 effect on aborts, 4-11 
Routing, 1-3 effect on DECnet/E programs, 4-11 
cost, 1-4 effect on disconnects, 4-11 
hop, 1-2 message limit, 4-11 
network diameter, 1-2 timing, 4-10 
path, 1-2 Transport Protocol, 
path length, 1-2 See TRN | 
Routing node, 1-4 TRN, 1-3, 1-5, 3-2 . 
RSTS/E system monitor, 1-4, 3-1, 5-1 Truncation of received messages, 3-3, 5-53, 5-54 
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U User Identification Code, 
See PPN 
ULA, 2-2, 3-12 ae ecrr yaaa 
User data accompanying messages, 3-3, 3-10, 3-12 be 
User events, 3-2, 3-5 
class and type, 5-14 


entity, 5-15 
parameter data, 5-15 Virtual terminal, 
system call, 5-14 to 5-17 See NET 
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